[fpc-devel] FPDoc sources

[Michael Van Canneyt]

On Tue, 30 Aug 2011, Hans-Peter Diettrich wrote:

> michael.vancanneyt at wisa.be schrieb:
>
>> Since the purpose of fpdoc is to document things from pascal source code,
>> for me it follows that it must read the source code first.
>
> This is the purpose of makeskel. Afterwards useful information has to be 
> added to all items, before finally meaningful documentation can be generated.
>
>> If it were any other way, we wouldn't need source code or XML, we could 
>> just
>> use Open Office or Word, that would be equally useful.
>
> Documentation of course needs a structure, and that structure is fully 
> contained in the xml files.

No it is not.
I think you should have a good look at the XML files before writing statements 
like that.

Take an enumerated:
TMyEnum = (One, Two)

It ends up in the XML file as 3 identifiers:
<element name="TMyEnum">
<element name="TMyEnum.One">
<element name="TMyEnum.Two">

All pascal information is lost. Only names exist, without any relations 
and no type info whatsoever.

>From the above XML information you could document equally well
a record
   tmyenum = record one,two : integer end;
a procedure,
   procedure tmyenum (one,two : string);
an enum
   TMyEnum = (One, Two)
A class:
   TMyEnum = Class
     Function One;
     Property Two
   end;

so from this information, you could never reconstruct the pascal structures 
it is supposed to document. (and which of course should reside in the docs)

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.

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

Michael.