Sign in Join

Live chat for Free Pascal, Lazarus, Delphi and every Pascal programmer.

Mailing lists / fpc-devel / 2010-08

fpc docs have hidden documentation

5 messages · 3 people ·

Reply by email Subscribe to this list Your subscription

Read-only archive. Use j and k to move between messages.

Graeme Geldenhuys

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?

All documentation output formats are affected. Take a look at this URL, and the link right at the bottom of the page. TThread.Execute points to nothing specific, but TThread itself.

http://www.freepascal.org/docs-html/rtl/classes/tthread.html

That's one example, there are about 6 or so of them.

Regards,
- Graeme -

fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal http://opensoft.homeip.net/fpgui/

Reply by email

Michael Van Canneyt
to Graeme Geldenhuys
Graeme Geldenhuys wrote 14 lines
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.

Michael.

Reply by email

Sven Barth
to Michael Van Canneyt
Michael Van Canneyt wrote 29 lines
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?

Regards,
Sven

Reply by email

Michael Van Canneyt
to Sven Barth
Sven Barth wrote 33 lines
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.

Reply by email

Sven Barth
to Michael Van Canneyt
Michael Van Canneyt wrote 51 lines
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 - 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

Reply by email