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".
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.
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 would love to be able to use fpc, as it's pretty much the only game in
town when it comes to a cross-platform Pascal able to be used for
low-level, even bare metal programming. I also realize that
documentation is often low on the list of priorities - but good
documentation is vital to build a user base, and bad documentation is
what drives people away.
-Jim
_______________________________________________
fpc-pascal maillist - fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
