[fpc-devel] fpdoc inherited entries

[Mattias Gärtner]

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?


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


Mattias