Re: A question about doxygen comments

[Gabriel Dos Reis <gdr at codesourcery dot com>]

Phil Edwards <phil@jaj.com> writes:

| On Sun, Apr 14, 2002 at 10:23:06PM +0200, Gabriel Dos Reis wrote:
| > 
| > While I was browsing some files in include/, I came across the
| > following comments in std/std_streambuf.h
| > 
| > /** @file streambuf
| >  *  This is a Standard C++ Library header.  You should @c #include this header
| >  *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
| >  */
| > 
| > Given that the above is from an 'std_*.h' file, can someone tell me
| > what it should mean?
| 
| The phrase "this header" in the comment refers to the name "streambuf".
| 
| Due to the way Doxygen associates entities with files, sometimes a
| class/function will be documented as "defined in the file bits/stl_foo.h,"
| to give an example.  We don't control that wording, so I thought it useful
| to explicitly tell the user which headers should and should not be included.

I understand that telling used not to #include stl_foo.h is right.  It
is disturbing to see the above in a stl_fool.h.  Is there be away
of "setting an alias for files" for doxygen?

| It becomes slightly clearer if you browse the Doxygen pages.

It makes Doxygen's life easier, it makes my (human) life slightly
disturbed.  Never mind ;-)

-- Gaby