Hi [me again], :)

The 'link' attribute inside section tags where introduced so that descendant classes can link documentation from base classes - without having to duplicate the documentation.

eg:

   TBaseButton = class()
   protected
     property ImageName: string....;      //<-- docs done here
   end;
   TButton = class(TBaseClass)
   published
     property ImageName;        // <-- docs here is a link to base class
   end;

This works in the HTML output writer (which isn't a linear writer descendant). This doesn't work in any of the Linear output writers. Was this by design - maybe to prevent duplicate documentation in PDF's or something? Or simply another oversight?

Regards,
- Graeme -

Op 2010-08-13 14:02, Graeme Geldenhuys het geskryf:

This works in the HTML output writer (which isn't a linear writer descendant). This doesn't work in any of the Linear output writers. Was this by design - maybe to prevent duplicate documentation in PDF's or something? Or simply another oversight?

I went ahead and implemented this as I would like this in IPF output. Michael, if you don't agree that this must work on all Linear output writers (like LaTeX, RTF etc), then please let me know, and I'll modify fpdoc accordingly - before I supply a patch.

Regards,
- Graeme -

[... sorry I only noticed now my Subj line is wrong. It should read Element tags...]

Michael,

Due to lack of documentation regarding the link attribute in Element tags, how are link attributes supposed be be handled. ps: I'm looking at the latest PDF docs of the last FPC release.

eg:
What happens if an Element tag has a link attribute, but that element node also contains ShortDescr, Descr, SeeAlso etc nodes? Does the link attribute take preference, and the child nodes of that Element gets ignored?

To me the above make sense because the link attribute is at the Element level. Otherwise it overly complicates matters - and I think will just confuse documentation writers.

BTW:
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.

BTW #2:
Please tell me the link attribute is only allowed in the Element tag, and not in other tags? :-)

Regards,
- Graeme -

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.

It should of course take precedence.

Seems correct.

BTW #2: Please tell me the link attribute is only allowed in the Element tag, and not in other tags? :-)

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

Michael.

Op 2010-08-13 16:01, Michael Van Canneyt het geskryf:

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

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 -

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.

Yes.

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.