Menu
▾
▴
#22 JavaDoc-like Tag handling
A couple of things that I think would absolutely love to
see PasDoc do -- firstly, be able to use un-
parenthesised tags, i.e.
@author Damien
@abstract A little bit about this
@created 2005-04-24
I try to write all my doc comments in a way that they're
just as easy to read, and hence just as useful, whilst
developing as when they're compiled, and being able to
do the above would improve the readablility 100% IMO.
Another thing I'd find immensely useful is being able to
put my doc comments in the implementation section
instead of the interface. Personally, I like a clean and
uncluttered interface so that I can easily see an overview
of each class without having to worry about the details,
no matter what editor I have to hand.
Logged In: YES
user_id=987895
Unparenthesised tags: this was often requested, and today
I realized that it's quite simple to implement. So it's
implemented now. See
http://pasdoc.sipsolutions.net/TagsParametersWithoutParens
Comments in implementation:
Theoretical reasoning why it's not good idea are
Comments inside implementation are meant for people
reading (or modifying) the implementation. So they are not
the right place for documentation for people merely using
the functionality.
The lack of "clean and uncluttered" interface is indeed
disadvantage of placing comments in interface section. But I
see it like this: interface section without comments looks
more clear, but is actually useless for a reader that wants
to get familiar with the code. If you want to see "clean and
uncluttered" interface than either 1. look at documentation
generated by pasdoc (not unit source), or 2. you may want to
specify comments completely outside the source code, e.g.
see fpdoc -- this is a program like pasdoc, but it reads
documentation strings from a separate XML file.
I know that above reasons are not a definitive "this is bad"
statements, but I tried to explain why it's a low priority
thing for me.
From a practical side, pasdoc currently parses only unit's
interface section. This obviously simplifies parser
implementation a lot. Reading comments inside implementation
section would require implementing parsing of unit's
implementation section. This would be significant work.
In summary: For me, this is large work, for no real gain.
That's why I will not implement it. So I'm changing priority
to 1. If for a long time noone will be interested in
implementing this feature, this request will be closed.
Logged In: YES
user_id=615525
Cool, thanks for your efforts.
Shortly after I submitted this request I downloaded the source
just to see how hard it would be to code the changes by
myself, and noticed the interface-only parsing. So, knowing
this, I completely agree that it'd be a lot of work for very little
gain.
Logged In: YES
user_id=987895
Since the feature of parsing implementation section was
already request by 3 different people, and it's not
something unsensible, I'm changing priority of this RFE back
to normal (5). See the bottom of page
http://pasdoc.sipsolutions.net/WantedFeatures for some "call
for help" about this feature.