Re: [patch] Doxygen tweaks

[Jonathan Wakely <cow at compsoc dot man dot ac dot uk>]

On Fri, Nov 19, 2004 at 12:58:04AM -0500, Phil Edwards wrote:

> On Thu, Nov 18, 2004 at 10:49:17AM +0000, Jonathan Wakely wrote:
> > 
> > If you leave the argument to @file blank then Doxygen applies the
> > documentation to the current file, which is unambiguous and <algorithm>
> > gets its own page.
> 
> The point of the @file renaming was that the entities which the standard
> says are in <algorithm> show up in doxygen as existing in <algorithm>,
> even though we implement them in std_algorithm.h or whatever.  I can't
> tell from your description whether this still holds true; does it?

It didn't apply anyway, from what I've observed. My patch certainly
doesn't preserve/restore that behaviour. See the latest-doxygen online:

http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/algorithm.html

That file links to the other headers that actually implement the
functions, but doesn't contain them directly. (Have I misunderstood?)

IIUC for that to work stl_algo.h would have to have "@file algorithm",
but it has "@file stl_algo.h" and so gets its own page under its own
name.


My patch is supposed to let doxygen interpret "@file algorithm" as
applying to <algorithm> and not <ext/algorithm>, and "@file memory" as
applying to <memory> not <ext/memory> or <tr1/memory> (*)

Otherwise Doxygen thinks we've just forgotten to give the directory
prefix (**) and ends up lumping the docs for <algorithm> under
<ext/algorithm> (although as visible at the URL given above, the docs
for <algorithm> are just the include guard #define (***))


I'll generate a set of docs and put bits of it online to show what I
mean, in case the behaviour's specific to my Doxygen version.

jon

(*) I have tr1/memory pretty much done and will submit soon.

(**) I would argue that in the absence of a prefix on the name Doxygen
should take the file that matches without a prefix, which would do the
Right Thing. But that isn't how it works, for now at least. I've been
thinking of filing a bug.

(***) we should probably prevent doxygen documenting the include guards,
so people don't think they can rely on those names being fixed, or maybe
only document them in maintainer mode

-- 
"You can have my encryption algorithm, I thought to myself,
 when you pry my cold dead fingers from its private key."
	- Decrypting the Puzzle Palace, John Perry Barlow