[fpc-devel] fpc docs have hidden documentation

[Sven Barth]

Am 27.08.2010 13:40, schrieb Michael Van Canneyt:
>
>
> On Fri, 27 Aug 2010, Sven Barth wrote:
>
>> Am 27.08.2010 13:11, schrieb Michael Van Canneyt:
>>>
>>>
>>> On Fri, 27 Aug 2010, Graeme Geldenhuys wrote:
>>>
>>>> Hi
>>>>
>>>> In the case of Classes unit documentation - more specifically the
>>>> TThread
>>>> documentation. The default behaviour when making RTL documentation, is
>>>> for
>>>> it to hide/exclude the "protected" section from the docs.
>>>>
>>>> This includes the TThread.Execute and TThread.Synchronize methods,
>>>> which
>>>> actually has documentation elements in the classes.xml file.
>>>>
>>>> Now the problem is, some other areas of TThread docs reference the
>>>> documentation of TThread.Execute and TThread.Synchronize. Because they
>>>> are
>>>> protected, they are excluded from the docs - causing unresolved links.
>>>>
>>>> Should we just ignore this problem?
>>>
>>> We should not, but it's hard to give a satisfactory solution.
>>>
>>> It is, in fact, a known problem since quite some time.
>>>
>>> The only thing I can come up with is a 'ignorevisibility' attribute
>>> in the description file's <element> tag for methods that you do want
>>> shown. But it then requires 2 passes in the documentation generator for
>>> protected/private sections.
>>
>> Out of curiosity: Why is the "protected" section excluded in the RTL
>> documentation?
>
> Because
>
> a) it is end-user documentation, not class-writers documentation.
>
> b) If I must document protected methods as well, the day needs 48 hours
> instead of 24.
>
> Michael.
> _______________________________________________
> fpc-devel maillist - fpc-devel at lists.freepascal.org
> http://lists.freepascal.org/mailman/listinfo/fpc-devel

But isn't a end-user often a class-writer as well? Especially in cases 
like the TThread class?

The second reason is valid though. I know that problem as well...

Regards,
Sven