[fpc-pascal] TFPGObjectList error

[Michael Van Canneyt]

On Sun, 1 Jul 2018, Jim Lee wrote:

>
>
> On 07/01/18 12:28, Michael Van Canneyt wrote:
>>
>> 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.
>>
>
> Thanks.  The user's guide, programmer's guide, and language reference 
> manual all say they are for version 3.0.2.  Perhaps the current version 
> didn't require any documentation changes?

Seems I forgot to update the symlink when we released. I fixed that. Thanks
for pointing it out.

>
>> If you think it is too terse in places, please report them in the
>> bugtracker. I will always fix all such reports.
>>
>>
>
> That really wasn't my point.  From the point of view of someone just 
> coming to fpc,  the documentation is the "face" of the product.  If that 
> face is ugly or hard to navigate, they are likely to just walk away.   
> Getting involved in the bugtracker is for people already invested in 
> fpc, and familiar enough with it to not *need* the documentation.

I consider this an error in your reasoning. 
The bugtracker is very lowlevel, and should be usable and familiar for all. 
Many of the documentation bugreports are from one-time users, people I never
have heard from.

>> 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
>>
>
> Perhaps the rtl is more complete than the rest - I'll take your word for 
> it.  I know it's a tremendous amount of work!
>
> The class library chart on that page is nice, but it's 11 years old 
> (dated 2007).

This is known. I better remove it, it does more damage than good now.

>
>> 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
>>
>
> An auto-generated index of all identifiers used across all modules is 
> useful, if you know what you're looking for.  Say I was looking for 
> something like a Timer class - where do I start?  Would it be in the 
> rtl, the fcl, or somewhere else?  Would it be named Timer, TTimer, or 
> something else?  I can't find an index that has an entry for "timer" and 
> points to all the timer-related things.

In the absence of a search mechanism:

You would get a long way if go to the FCL page, press ctrl-f and type timer
in the search box of your browser..
The 4th hit on the page gives you fptimer, the unit that contains a
timer.

But most of the time when I search for something, I just enter google, type
"free pascal timer". The third hit is the same as the one I mention above.
You can't beat google for ease of use and accuracy.

>> 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.
>>
>
> Pardon my ignorance, but I take it that "packages" is more like an 
> un-curated repository of contributions rather than an official part of 
> the fpc distribution?  If so, I wasn't aware of that.  It would explain 
> a big part of my frustration.

FPC's "packages" are not uncurated. They are mostly import units, allowing you to
work with all kinds of open source libraries. On top of these e.g. the data acces
units are built.

But I know that search is an issue, hence my question "what is the problem
with the documentation _besides_ search".

Contrary to what it may seem it is not so easy to make a search engine for
the documentation. I've had several shots at it, but have not yet come up
with a good mechanism. The last mechanism I tried ended up indexing more
than 24 hours before I killed it.

Contributions or ideas welcome.

Michael.