[fpc-pascal] State of FPC docs.rant

[Graeme Geldenhuys]

On 25 April 2010 21:48, Joseph Montanez wrote:
> Since there hasn't been a clear response on this I've started my own
> website, to start documenting more of the use of each library.

The class documentation generated by fpdoc has support for examples.
FPC's policy is to only publish documentation on units that have been
fully documented.  Your mileage my vary on what "fully documented"
means. ;-)  This is different to the documentation style of for
example Lazarus LCL, where automated "template" documentation is
generated for all units - most being undocumented.

Looking at your website, that is exactly the kind of code examples
that should be included with the official documentation. I think the
preferred location should be with the existing RTL and FCL
documentation. I don't see a benefit in having fragmented
documentation over various websites and locations. This makes it near
impossible for a end-user to find help.

I would suggest you checkout the latest copy of the documentation
SubVersion repository:

   http://svn.freepascal.org/svn/fpcdocs/trunk

Then submit code examples for the various units.

Here is an example of fpdoc documentation generated with images and
examples, for another open source project I work on, called tiOPF
(Object Persistent Framework).

  http://opensoft.homeip.net/tiopf/core/titokenlibrary/index.html
  http://opensoft.homeip.net/tiopf/core/titokenlibrary/ttokens.html


Image support inside fpdoc was added a few months ago, but I don't
think RTL or FCL docs take advantage of it yet. This could be useful
for UML or Class diagrams as well - being part of the official
documentation.

I'm sure I am speaking for the whole FPC community, that it is great
to see people other than Michael van Canneyt help out with the
documentation. But I still think we must try to keep documentation
together and part of the official documentation as much as possible.
The end-users and developers using FPC which find it [the help with
examples] easier and be more helpful in the long run.


-- 
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/