[v3] List docs

[Phil Edwards]

On Tue, Jul 15, 2003 at 09:30:34AM -0400, Jerry Quinn wrote:
> I went back and added @a markers and verified both line wrapping and
> that make works.  Checked in.

Thanks.  I should have added that @p has pretty much the same effect as @a,
so in the places where you already have @p, don't bother changing them to @a.
We just need /something/ in there.


> One thing I didn't like in the generated output was that the page for
> list had function descriptions beginning with:
> 
> template<typename Tp, typename Allocator=allocator<Tp> >
> std::list<Tp, Allocator>member_function(...)
> 
> Would it be possible to get rid of the <Tp, Allocator> from std::list?
> It's redundant since this is't a specialization and make for harder
> reading, I think.

I agree it's redundant and ugly.  You should take a look at run_doxygen,
where we do a bit of massaging on the output files.  Running the particular
pages through sed would do it.  Only a couple of points:

- As you say, we would want to keep specializations, so the removal pattern
must be chosen carefully.

- Ideally, IMHO, we'd remove the template "adornment" for container X
only on the page for container X.  The problem is that we have no way of
predicting or determining[*] that, say, std::list will be documented in
"classstd_1_1list.html".  The "mangling" occasionally changes.

- The <Tp, Allocator> also shows up elsewhere on the page, e.g., the header
and title.  We probably want to keep those.


Phil
[*]  That's a minor lie.  I have a kludgy script that tries to figure out
the contents of namespacestd.html (index -> "Namespace List" -> "std")
and extract the main pages' names.  It lets me do things like

    http://www.devphil.com/libref/std::list

but is very very fragile.  The Doxygen author has just given me an idea
for a different way of finding the generated filenames.  If it works,
we can use that mapping elsewhere.

-- 
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