[fpc-devel] fpdoc inherited entries
nc-gaertnma at netcologne.de
Mon Feb 18 13:10:51 CET 2008
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
> > 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
> > the ancestor property/method/variable, right? (It's ok if the overridden
> > 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
> 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.
More information about the fpc-devel