A question about doxygen comments

[Phil Edwards]

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.

It becomes slightly clearer if you browse the Doxygen pages.


Phil

-- 
If ye love wealth greater than liberty, the tranquility of servitude greater
than the animating contest for freedom, go home and leave us in peace.  We seek
not your counsel, nor your arms.  Crouch down and lick the hand that feeds you;
and may posterity forget that ye were our countrymen.            - Samuel Adams