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

[Michael Van Canneyt]

On Fri, 13 Aug 2010, Graeme Geldenhuys wrote:

> 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>

First of all, the above must be reduced to 
<element name="TDatabase.Connected" link="TCustomConnection.Connected"/>

It makes no sense to have the 'link' attribute and have content for the
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?

Yes.
>
> 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].

I'm not sure I understand what you want.

What do you propose ? To duplicate the documentation in the output ? 
The whole point of <link> is that this does not happen. It's a waste of
space. If you want to duplicate the documentation, then explicitly 
duplicate it.

Michael.