[fpc-pascal] State of FPC docs.rant

[Joseph Montanez]

<rant>
I use php, c / c++, vala, java, actionscript, python, javascript and
of course pascal.

When I was introduce to pascal it was Delphi, but then I ran into Free
pascal and a tiny bit of the pascal community, this mailing list. One
of the biggest problems I am having with pascal is learning the
libraries. There are plenty of resource to learn how to make
procedures, classes, objects, etc, but almost nothing on using the
libraries. Not so much the libraries others make (SDL for example) but
the ones baked into FPC.

Great example:
"TFPObjectHashTable" has docs, great but no use case or draw backs
using this. I searched google, google code and github not a single
code example of it being used. How can a library put in place with no
demo? Is there not even a unit test case to look at?

You know what fine, I know how to program, So I can read the docs.
However here is the kicker, the current state of the docs doesn't
really have an ability to just throw up revisions. Instead there is
the Wiki, so my true value of this post is...

I am more then willing to provide a better doc, but should it be done
in the wiki or should I just span off into my own little world onto my
website? An example of what I think a good doc would look like would
probably be alone the lines of:
http://gorilla3d.com/v8/wiki/doku.php?id=mysqli_db (self promotion I
know) but its very php.net like. Not just here are the parameters and
their descriptions but how to used each function in the entire scheme
of things.

In the end I think automated documentation is bad, and thats really
what I see with the current state of FPC docs. It might allow better
ability to stay sync with the current release but not allowing _easy_
social interaction to expand those docs, I think it is a big mistake.
</rant>

-- 
Joseph Montanez
Web Developer
Gorilla3D
Design, Develop, Deploy