[fpc-devel] FPDoc sources

[Marco van de Voort]

In our previous episode, Graeme Geldenhuys said:
> > This is the purpose of makeskel. Afterwards useful information has to be
> > added to all items, before finally meaningful documentation can be
> > generated.
> 
> I personally think makeskel is a terrible idea. It generates a whole
> bunch of elements making it really hard to find out what is and what
> isn't documented. It also generates lots of unnecessary elements -
> obfuscating the xml and documentation more.

Only the former. Generation of documentation for empty nodes can be
surpressed in fpdoc.
 
> > contained in the xml files. There exists no need for adding further
> > information from the source code, that's more eye candy than essential
> > information.
> 
> I beg to differ. Seeing the signature of a method, procedure, function
> etc is valuable information to a developer.

True. But that doesn't make it important to be in every fileformat.

> Not all IDE's or programming editors support "parameter hints", or some
> developers prefer to keep such feature disabled to speed up the
> editor/ide.  So having such information [method signatures] available in
> the help is very useful.

Which is the case now, even though they are not in the XML. Stronger even,
if you have an IDE that can't parse the source to get that info, you could
develop a fairly simple fpdoc backend to generate a helper file for the IDE.

> Having a inheritance hierarchy is also very valuable, which the
> current fpdoc XML format doesn't describe at all. This information is
> only available when parsing the pascal source code.

No. You can also get it from the .xct's, which, for the last release, are
available in the doc-chm package. The 2.4.4 release is the first that also
contains interface inheritance data.

That being said, the .xct format is a bit cumbersome, and I believe Michael
already planned to change it to XML.