In the LCL there is documentation for TControl.Caption which is useful for all descendant classes like TButton.Caption too. It would be nice if fpdoc shows the content of TControl.Caption if TButton.Caption does not have a value or at least show a link to the inherited entries.

Comments?

Mattias

That will be a excellent feature! I believe I put in a feature request for that already. I'll have to double check. One big time saver will be less document duplication. Like you said, base classes can be documented and a lot of it probably applies to descendants.

Regards,
- Graeme -

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

This is in mantis as a feature request, but it is not easy to implement.

Feel free to do a proposition. I'll then do the implementation :-)

Michael.

Make it mandatory to flag such properties if you want to use this feature. Nobody is interested in all inbetween properties and symbols.

Zitat von Michael Van Canneyt :

I added a button to the IDE built in fpdoc editor to automatically create a 'see also' link to the next documented ancestor entry.

Feel free to do a proposition. I'll then do the implementation :-)

That's an amazing offer.

fpdoc already knows the ancestor classes. So it should be possible to find out the ancestor property/method/variable, right? (It's ok if the overridden method search is not 100% perfect)

If yes, then it might be possible to traverse through all ancestors and find the next existing short description, right?

Mattias

The problem is that you may or may not have the definition (and corresponding page) in memory. If the parent def (and doc) is not in memory, you don't know whether a page is available or not.

If yes, then it might be possible to traverse through all ancestors and find the next existing short description, right?

In theory, yes.

Then you need to decide what to do:
- Create a page for TChild.Property and simply refer to TParent.property (a braindead solution imho)
- do not generate a page but In the 'Property/methods/Class overview' of TChild, refer to TParent.property whenever TChild.Property is not documented.

In the latter case, pressing F1 on TChild.Property will refer to a non-existing page.

Michael.

Zitat von Michael Van Canneyt :

How do the links to the ancestor classes work?

:)

The final presentation whether fpdoc creates a 'see also' link OR copies the content OR refers directly is a second step. First fpdoc must gather some data:

It should only refer, iff the TChild.Property is not documented (= has no short description) and iff there is a documented TParent.Property, where TParent does not need to be the direct ancestor. For example TButton.Caption should not refer to TCustomButton.Caption nor TWinControl.Caption, but to TControl.Caption.

Mattias

Michael Van Canneyt wrote

Then you need to decide what to do: - Create a page for TChild.Property and simply refer to TParent.property (a braindead solution imho)

Why is creating a link from TChild.Property to TParent.Property a bad thing?

AFAIK, if you use Doc-o-Mactic it will do exactly that. Delphi help also works like that. In fact, I don't know any example of a source code documenting system that copyes the same text on several places for the same function.

Through a complicated search mechanism :-)

I am more in favour of adding a new attribute to allow more control by the documentor:

<element name="TButton.Caption" link="TControl.Caption"/>

It has the advantage of being faster as well: the documenting process can use some speedup, it gets slower by the day. The disadvantage is that you must fill it in manually - although a simple button in the editor can take care of that:
- fill this property for the current element,
or
- for all elements with <fill your favorite recipe here> fill the closest ancestor.

Michael.

Because you don't need the TChild.Property should not be a link to TChild.Property anywhere. All links should always be to TParent.property.

In the overview page:

Class TChild
...
Properties
...
Property MyProperty; --> link to TParent.MyProperty, NOT to TChild.Property

Delphi uses the second mechanism which I proposed (the not-braindead-one).

In the 'TFileStream Methods', just click on TFileStream.WriteBuffer, under 'Derived from TStream', and it takes you to to TStream.WriteBuffer.

The braindead one would take you to a mostly empty page TFileStream.WriteBuffer with a small clickable text 'This method is documented in TStream.WriteBuffer.'

Michael.

Michael Van Canneyt wrote

Because you don't need the TChild.Property page at all. There should not be a link to TChild.Property anywhere. All links should always be to TParent.property.

Ah ... ok, I misunderstood you. We have the same oppinion =)

Zitat von Michael Van Canneyt :

Ok.

Ey, I thought I do the proposal and you do the implementation!? Now it seems I have to implement this 'for all elements' function in the editor.

Will you implement the fpdoc part, that means the 'link' attribute, so that fpdoc does not create the TChild.Property pages and instead directly links to the linked page and update the fpdoc docs?

Mattias

Hehe :)

Now it seems I have to implement this 'for all elements' function in the editor.

Clever twist of me, eh ? ;-)

Will you implement the fpdoc part, that means the 'link' attribute, so that fpdoc does not create the TChild.Property pages and instead directly links to the linked page and update the fpdoc docs?

Yes.

It means a lot of checking, though, because all <link id=""> references to TChild.Property must also be changed. If speed is affected, maybe I'll have to do some tricks in the search mechanism as well :(

Michael.