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

[Martin]

On 31/08/2011 13:17, michael.vancanneyt at wisa.be wrote:
>
>
> On Wed, 31 Aug 2011, Martin wrote:
>> 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.
see also is different

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

that can only be confirmed/decided by the author of the code/docs.

The original mail, that triggered the idea was:

On 31/08/2011 09:43, Hans-Peter Diettrich wrote:
>
> 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.

Indicating the desire to have the documentation of the enum exclusively 
within one property.

Currently that can be done, by just putting it there by hand.

That of course means, should you ever have to link it (which in the 
avbove case should not be needed / if it was needed it should likely not 
have been embedded) then the author has to remember to put in the 
corrected link himself

Putting the enum manually into the property however means more work, if 
it should later be needed to move to it's own help-page.