On Sun, 1 Jul 2018, Jim Lee wrote:
On 07/01/18 01:03, Michael Van Canneyt wrote:
Can you explain what you think is wrong with or missing in the
official documentation ?
(apart from a search mechanism)
Michael.
Well, search is a big one, but there seems to be a lot of missing pieces
(again, without search it's hard to tell exactly how much is missing).
There also seems to be a lot of outdated stuff, and most of what I find
was auto-generated from fpdoc (when? last week or 10 years ago? no
timestamps!), with scant (or no) explanation beyond "here is a terse,
un-commented example".
The documentation is brought up to date at every release: all new
identifiers are documented and the documentation regenerated.
If you look in the bugtracker, you will see that I regularly fix
documentation issues.
If you think it is too terse in places, please report them in the
bugtracker. I will always fix all such reports.
I haven't found any sort of map or tree that shows how the rtl and fcl
are organized, or an index that shows which types/functions/classes are
in which units (that's hugely important). Basically, I expected to find
the equivalent of the old Borland programmer's reference manuals.
It is all there, user's guide, language reference, programmer's guide,
Reference to *all* rtl units. What do you think is missing ?
See https://www.freepascal.org/docs.var
index:
RTL: https://www.freepascal.org/docs-html/current/rtl/index-8.html
FCL: https://www.freepascal.org/docs-html/current/fcl/index-8.html
The most common scenario for me is this: "I wonder if fpc (or Lazarus)
already has <insert feature here>". Go to the wiki and browse
haphazardly, looking for something named similarly. If that something
is found, and looks promising, follow link to a half-page of
"documentation" which is basically just a snippet of the interface
section in the source. Then, try to find the referenced module in my
local source tree and discover that it's not quite the same, or is not
what I was looking for in the first place. Rinse and repeat.
I don't know what documentation you are referring to, but as said, all basic
RTL units, and selected FCL units are documented:
https://www.freepascal.org/docs.var
Packages are another story. I checked the packages. There are roughly 16.000
classes.
I didn't count methods/functions, but they surely are a multiple of that.
There is 1 documenter: me.
I have toyed with the idea to run fpDoc on all packages, and put the result
online, so people can at least have a look in the index to see what's
available.,
Feel free to chip in.
Michael.
_______________________________________________
fpc-pascal maillist - fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
