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

[Martin]

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.
An fpcod-editor/ide could also check that all elements of the source do 
have documentation (or tell you about new elements that yet need 
documentation)