[fpc-devel] fpdoc's link attribute in Section tags

[Graeme Geldenhuys]

Op 2010-08-13 16:01, Michael Van Canneyt het geskryf:
> 
> In my opinion, the overview of a class member should simply refer to the
> page containing the parent's implementation (i.e. the target of the link).
> 
> It should not duplicate the documentation.

As far as I understand the current PDF docs are generated with FPC 2.4.x so
the link attribute is not supported there.  But looking at the current
documentation [as seen in FCL.pdf], eg: TDatabase.Connection has
documentation, and so does TCustomConnection.Connection. The documentation
is already duplicated in the current docs.



<element name="TDatabase.Connected" link="TCustomConnection.Connected">
<short>Is the datbase connected</short>
<descr>
<var>Connected</var> is simply promoted to published property from <link
id="TCustomConnection.Connected"/>.
</descr>
<seealso>
<link id="TCustomConnection.Connected"/>
</seealso>
</element>


In the case of fpdoc v2.5.x you mean you don't want any documentation for
TDatabase.Connection, other than a link to Page xxx in the Method Overview
and Property Overview tables for TDatabase?

So that means TDatabase will only have two Overview tables, nothing else?
But what if you now decide to write extended documentation for
TDatabase.Connected for whatever reason, and remove the 'link' attribute.
Then the TDatabase chapter will have two overview tables, and one section
TDatabase.Connected with the new documentation. That will look weird - as
if TDatabase wasn't documented at all, other than that one property.

If that is indeed what you want, then I'll have to add a parameter or
something to fpdoc to alternate between what I want and what you want. What
you describe doesn't look so nice to me [personal opinion here].


>> The HTML output writer works as I described above. If the link attribute
>> exists inside a Element tag, the child nodes of that Element is ignored. I
>> implemented the Linear output writers behaviour to follow the same rules.
> 
> Seems correct.

Perfect!


> It is only allowed in the element tag, and should be observed only for class
> members. It makes no sense otherwise.

Yes, that makes sense.



Regards,
  - Graeme -

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