On Fri, 6 Jan 2012, dhkblas...@zeelandnet.nl wrote:
Resending the email. The images are here:
http://imagebin.org/192019 [3]
http://imagebin.org/192020 [4]
http://imagebin.org/192021 [5]
On 6 jan '12,
dhkblas...@zeelandnet.nl wrote:
I checked doxygen
(http://www.stack.nl/~dimitri/doxygen/examples/overload/html/class_test.html#a8e7b46ceaf7bd2ab94114b390b3288ca
[1]), but it does not seem to list the variables. Pasdoc does not seem
to group overloaded functions, but rather list them separate in a table
(http://pasdoc.sourceforge.net/autodoc/html/PasDoc_Gen.TDocGenerator.html#WriteConverted
[2])
On a side note,
1) for overloaded functions it seems
that only one result string is possible to define. As seen in the XML
file:(no desitinction based on result type)
Correct.
2) string variables or
result types do not show in my documentation (as do more complex result
types as arrays, please look to the screenshots) seems to be a bug??
Indeed. What version of fpdoc are you using ?
Anyway, I have created a mockup for a slightly modified result from
fpdoc as seen in the screenshots. What has changed:
1) All
arguments are mixed into one table
This is very good.
2) The result types are also
put in a result table (needs modification in the XML as described above)
I don't think this is good. The XML elements are name based, lookups are
or can be done on name only.
3) initialized variables (style: integer = 0) are automatically
added to the description eg (default = 0)
I think this is redundant information because it
a) appears in the declaration
b) can be mentioned in the short description.
But it can definitely be an option: --document-argument-defaults
A second mockup adds the
argument and result type description as "comments" to the declaration
section. This eliminates the need to have a variable section completely.
It also adds the possibility to add different comments per overloaded
function even on variable level. Personally I like the comments approach
as it makes the documentation page nice and compact.
I will not discuss taste, but what if there are references in the short description ?
You can't nicely handle that in comments, so I think this should be an option as
well: --document-arguments-inline
Michael.
_______________________________________________
fpc-pascal maillist - fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
