[fpc-devel] fpdoc inherited entries

[Michael Van Canneyt]

On Mon, 18 Feb 2008, Mattias Gärtner wrote:

> Zitat von Michael Van Canneyt <michael at freepascal.org>:
> 
> >
> >
> > On Mon, 18 Feb 2008, Mattias Gärtner wrote:
> >
> > > Zitat von Michael Van Canneyt <michael at freepascal.org>:
> > >
> > > >
> > > >
> > > > On Sun, 17 Feb 2008, Mattias Gaertner wrote:
> > > >
> > > > >
> > > > > 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?
> > > >
> > > > This is in mantis as a feature request, but it is not easy to implement.
> > >
> > > 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)
> >
> > 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.
> 
> How do the links to the ancestor classes work?

Through a complicated search mechanism :-)

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

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.