[fpc-pascal] Documentation and posts suggestions [LONG]

[Michael Van Canneyt]

On Sun, 15 Mar 2009, Francisco Reyes wrote:

> 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.

The unit name is always displayed on the top of the page.

> * In cases were some code needs a particular mode other than the default mode
> we can include which mode is needed.

There is no need for this: Classes and exception handling always need mode objfpc 
or Delphi. Regular functions do not need a mode at all. 

This is a simple rule, which can easily be remembered, no ?

Michael.