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

[Martin]

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>

An editor may or may not use this to display info in different ways.

But when generating the final help, fpdoc would not generate a separate 
topic for TEnum. it would embed the documentation in the given other 
element (does not have to be a propert, could be anything).
And links in the documentation would be changed appropriately.

This would allow to document each element on it's own as currently. Yet 
allow the author to specify that no separate page should be created 
(which may lead to fragmentation of the docs).

-----------

Anyway, at this point it's only an idea. I have no use for it myself. 
But the original post *sounded* like this might be desired....