[fpc-devel] fpdoc inheritance diagrams improvements

[Marco van de Voort]

Hello,

Graeme filed a bugreport (15774) about inheritance diagrams.

Mostly he wanted interfaces in the inheritance, but while preparing that I
found out that inheritance diagrams were broken already. 

I fixed this, but there are several problems and conditions left, and this
message documents them, for interested people.

What is fixed exactly? Well, the contentfile (.xct) already contained
inheritance info, but it was incomplete (no implemented interfaces) and in
some cases inheritance info was not written, or not fully qualified.  Also,
on read of the contentfile didn't do anything with the inheritance info.

So essentially I fixed passrc to register implemented interfaces, improved
the writing of the content info, and fixed reading it back.  The next step
will be to add interface inheritance to the class inheritance section (in
html/chm docs), going from inheritance-chain to inheritance-tree.

There are a couple of issues though:

1. The first is not a bug, but a fpdoc condition that not everybody might
realize, most notably the Lazarus doc team, so I write it here, and CC this
to the lazarus list.

Units within a package must be imported in the rough inheritance order.  (so
e.g.  in the rtl package system, types, sysutils, classes etc).  This was
already so and hasn't changed. It is just more noticable :-)

For this, I moved the system dependancy in the FPC docs to be the first one
in the line, and that seems to solve it mostly. However the lazarus
documentation doesn't seem to have an order at all. The fpdoc argument list
is constructed by a script, which essentially boils down to alphabetical
order.

Probably the lazarus docs generation needs to be rethought, so that a
documenter can specify the order of units to process.

See also point 5 to detect this easily. In the inheritance a ? appears if
this happens.

2. Type aliases don't work properly

This has only one casualty (at least in rtl and fcl), IInterface.

IInterface is an alias for IUnknown, and thus a "type", not a "class", and
not searched for various inheritance related code.

Searching types also would be fine, but complicates the code tremendously.
Maybe some solution for this should be implemented in passrc (e.g.
tpasclasstype and a tpasclasstypealias that derive from the same
pasclasstypecustom or so)

3. the types unit is not in the RTL documentation

This breaks the interfaces chains, since Types contains e.g. IPersist.

4. The current system doesn't keep a distinction of implicit or explicit
inheritance. Not a big problem, and I don't see a case where it matters atm.
(this is only between packages. The original package and class decl will be
neat and show implicit inheritance or not) 

The biggest issue is probably CORBA interfaces, since these don't
implicitely inherit from iunknown, but currently they do.  Afaik passrc
doesn't consider CORBA interfaces at all atm.

5. I added a ifdef option in passrc (ifdef Inheritancewarnings) that prints 
 a warning if a class is defined with an ancestor type that can't be
resolved. (a dummy type is created in this case)

It is ifdef because passrc must be writeln() free, and there seems to be no
system to propagate notes back to engine.

greetings

Marco