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 12:46, michael.vancanneyt at wisa.be wrote:
>> On Wed, 31 Aug 2011, Martin wrote:
>> 
>>> 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 am not too familiar with fpdoc, so maybe something already exists.... but:
>
> I wasn't referring to where the *editor* is showing the information, not even 
> where it is in the xml.
>
> What I meant was:
> - TEnum.One / TEnum.One  /TEnum
>  are still each of them documented in their own xml node, exactly as they 
> currently are.
>
> But in TEnum xml node would be an attribute (or a node) declaring:
> <embed>SomePropertynameUsingTEnum</embed>

This is what the '<seealso>' is for.

It's not useful to have only 1 "priviledged" <embed> since an enum may be used 
in many properties of many classes.

In each case, the opposite is already so. The documentation of an
enumerated-typed property will normally link to the enumerated type.

Michael.