Explicit documentation should stand out from generated documentation (Origin: bugzilla #143388)

[doxygen]

trafficstars

status NEW severity enhancement in component general for --- Reported in version unspecified on platform Other Assigned to: Dimitri van Heesch

On 2004-05-30 08:31:54 +0000, Nick Welch wrote:

Say I have a method and I document what its arguments do:

/// @arg @c a: this is an argument
/// @arg @c b: this is another argument

and thus I get this in the generated html:

* a: this is an argument
* b: this is another argument

This documentation is, in my opinion, of much more interest to the person
looking at the docs than the generated stuff is, such as:

Reimplemented in foo, and bar.

Definition at line 123 of file blarg.hh.

References thing.

Referenced by another_thing.

Don't get me wrong -- the generated docs are important too, but when
visually
skimming the page, you want the human-written stuff to stand out.  I don't
really know what different formatting would be best; maybe bold?  Different
color?  I'm not sure.  Maybe put the human-written stuff in a little box
with a
different background color (light yellow, like a note, perhaps?)

On 2005-03-27 14:23:36 +0000, Dimitri van Heesch wrote:

Makes sense indeed. I'm even thinking about a section that can be
expanded/collapsed at runtime (via DHTML & Javascript). That way a reader
can
expand the information when needed.

[albert-github]

I've just pushed a proposed patch, pull request #9825