#36 more ad-hoc decisions to show or not show something
1) i'd like to be able to switch things, like "document or omit private members" on per-unit, then per-class basis. Something like CSS :-)
2) i'd like to be able to specify short descriptions for used units in modules, by putting coments directly in module, that uses them, such as .DPR project file, or (if missed there) from some @shortdesc in the used unit itself.
3) i'd like to see .DPR file at the top of units list. Full and elegant implementation might be the PasDoc2 goal to make dependacy-ordered list, though.
4) i'd like to be able to save some settings within the source files them selves, such as
4.1) used language/charset for sources and for output files
4.2) **-mode or other markers mode
4.3) auto-link or not, "document or omit private members" and alike options
Logged In: YES
user_id=406841
Originator: YES
Sure i filled i forgot something.
Why "ad-hoc" ? One more wish.
5) I'd like PasDoc to be able to omit private members, until i put comments on them (hence i want this certain items to be documented, no matter they are private)
Same for short units descriptions (wish 2), same for.... anything :-)
Logged In: YES
user_id=987895
Originator: NO
AD for 1) and 2) and 5): I honestly don't see much use for this.
AD 1): If you generate documentation, then you either omit internal information (private members) or not. What's the use of documentation with mixed things ? For single/exceptional cases, you can use @exclude tag.
AD 2): This complicates things, for pasdoc and for documentation writers. What happens when more than one description is available ?
AD 3) Full parsing of programs (.dpr) and automatic parsing of dependent units is indeed planned at some point. These are mentioned in WantedFeatures and PasDoc2 in the wiki. Indeed, placing .dpr files before units could be useful as soon as parsing the programs will get really useful.
AD 4) The only use is when you have documentation written using mixed styles (someone used markers, someone didn't, someone used Polish ISO-8859-2, someone used Russian ISO-xxx, etc., and there's no time to convert them at once to use consistent style). OK, I see the usefullness. Although:
- About "document or omit private members" see my answer to 1).
- About auto-link: @noAutoLinkHere and @noAutoLink provide some workarounds. Still, I understand that these are hard to use if you have many units, and for some units you want to turn auto-link on and for some you want to keep if off.
AD 5) What's the use ? The idea is that you document your units --- so everyone wants to see all things declared in the interface. Even without documentation, it's still useful to see the definition of some item. For exceptional cases (when you had to declare in the interface something that really should remain internal), there is @exclude. (And @excludeBegin and @excludeEnd are planned, see WantedFeatures in the wiki).