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)
_______________________________________________
fpc-devel maillist - [email protected]
http://lists.freepascal.org/mailman/listinfo/fpc-devel
