[fpc-devel] FPDoc sources

[Hans-Peter Diettrich]

Michael Van Canneyt schrieb:

> Now, you could "fix" that, of course.
> That would require you to copy all information which is contained in the 
> interface section of the pascal file to the XML file.
> 
> For example:
> <element name="TMyEnum" type="enumeration">
> <element name="TMyEnum.One" type="enumerationelement" Parent="TMyEnum">
> <element name="TMyEnum.Two" type="enumerationelement" Parent="TMyEnum">
> 
> But, copying this information to the XML file would be a) duplicate and 
> thus redundant information.
> b) require more work as soon as anything changes in the interface section.
> and therefor would be - in my eyes - extremely bad design.

Just this design is very questionable, with regards to useful 
documentation. My counterexample:

type
   TMyEnum = (one, two);
   TMySet = set of TMyEnum;
...
   property MyProp: TMySet read GetIt write SetIt;

Now we have 7 identifiers, all refering to the essentially same data 
type. IMO it's only excess work, to document all these elements by 
themselves, when finally only the property is of interest. Instead I'd 
prefer a single doc entry, for the property, that also describes the 
enum elements. All related elements then can be linked to that unique 
description.

> That's why the design is as it is and will not be changed anytime soon.

I don't ask for an change of the design, I only ask for a complete 
documentation, that includes all elements of the given xml files, even 
if no source files are given.

DoDi