On Wed, 31 Aug 2011, Martin wrote:
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.
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 can appreciate that this would be a useful option (and maybe even the
default view).
Michael.
_______________________________________________
fpc-devel maillist - [email protected]
http://lists.freepascal.org/mailman/listinfo/fpc-devel
