Whether coming from Delphi or a totally new to pascal user there are a
couple of changes we could made to the documentation to make it friendlier
and to posts we make on the list.
I was thinking that including the unit and, if needed, the compiler mode
for functions in the documentation may be very helpfull.
My example.
Have been following the list for a while. Have a few projects that I kept
thinking to do in FPC and have asked questions in the past about specific
functionality.
I finally sat down to start one project. Given an example I was given
some months back I set myself to try and get this to run:
var
SL: TStringList;
begin
SL := TStringList.Create;
try
SL.Delimiter := ',';
SL.DelimitedText := 'This,Is,Some,Delimited,Text';
ShowMessage(SL[0] + ' ' + SL[2]);
finally
SL.free;
end;
end.
I had no idea where TStringList was defined.
I have the PDF docs so was looking at the rtl pdf. From reading it I could
not figure out what unit I needd to include. Looking at the online reference
I saw on the top right "Reference fo unit classes" so I just included
classes.
Then I got errors because of the try. I knew this was object pascal so I
set to find which modes supported object pascal.
Lastly I got an error because of ShowMessage. After searching the web I see
that is in the dialogs unit. Even after including the dialogs unit it still
fails. In my simple program even a writeln will do the trick so I am
skipping this altogether.
Thoughts I gathered from this exercise:
* It would be helpfull if we included the uint for each function in the PDF
documentation. May be a little redundant, but I think often people will do a
find and will be looking at a partiduclar function in the PDF.
* In cases were some code needs a particular mode other than the
default mode we can include which mode is needed.
* If an example is Lazarus specific indicate so.
Looking at http://wiki.freepascal.org/Dialog_Examples I tried to copy/paste
the simple ShowMessage example in a program and it failed. I guess the code
may need Lazarus. Just looking at that page I have no idea what else I am
missing or if that is Lazarus only code. Given that someone could land on
that page, like I did, from a search it would help to indicate if that is
Lazarus only code.
* Lastly, I think the people in the list are extremely helpful, but
sometimes forget that what may be obvious to them (ie that a class needs to
be included) may not be obvious to the reader. So, it would be most helpfull
to include the "uses" section with an example. Obviously a good reply with a
few details missing is better than no reply at all, but figure that it would
save a little bit of back and forth if people remembered this detail.
If given any pointers of how to work on the docs and if some of my points
are though to be something we want to do, I could start working on this
myself.
_______________________________________________
fpc-pascal maillist - fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
