fpdoc extension: embed topic [Re: [fpc-devel] FPDoc sources]

[michael.vancanneyt at wisa.be]

On Wed, 31 Aug 2011, Martin wrote:

> On 31/08/2011 09:43, Hans-Peter Diettrich wrote:
>> 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.
>
> IMHO the location of where the enum is located is not relevant to the 
> requirement of (or ability to the do without) scanning the source.
>
> Never the less, this could be an interesting feature. If fpdoc could be told 
> (as part of the xml) that the documentation of an element should be embgedded 
> in the parent (enum element, in enum type), or even embedded in a specific 
> other node (a property specified by name, that uses the enum).
>
> Then fpdoc could also automatically adjust all links to those elements.

It could do this now already. It's just a matter of specifying an alias.
A rule like
TMyEnum. -> TMyOtherEnum.
would do it. (the dot meaning that all identifiers starting with TmYEnum
must be remapped)

But personally, I don't want the linear XML structure disturbed.
I edit the xml files manually, and having a 'tree like' XML then makes 
it more difficult to edit.

But the fpdoc editor is another matter. You could perfectly adapt lazde 
to show a tree:

TMyEnum
   +- One
   +- Two
Same for classes functions, procedures, whatnot. It's just a matter of
scanning the element name and creating separate nodes for each part in 
the dotted name.

I can appreciate that this would be a useful option (and maybe even the
default view).

Michael.