documentation example for std::priority_queue

[Benjamin Kosnik]

>That example was taken from the SGI docs which do a much better job
>than the current libstdc++ docs of giving examples and describing the
>STL components e.g.  http://www.sgi.com/tech/stl/priority_queue.html

Yep. We shouldn't be adding examples to the source code, but to separate
documenation pages. (IMHO).

>IMHO if we're going to do more than just document the functional
>interfaces and the parameters they take we should aim for something as
>useful as the SGI docs - which is a big job that *might* be better left
>to dedicated STL user-guides and/or tutorials.

Yep.

>I hope I haven't put you off contributing, as improvements to the
>documentation are much needed, but haphazardly adding just one example
>may not help much (others might disagree with me here).

Nope. I think that the current documentation can be improved, greatly.

I'm not sure how to start down that road, however. I do think that more
specific documentation, a la the debug mode docs or the current
allocator.html page is the way to go. I don't know how to get complete
coverage, however, or if that is a desired goal. (Or something we leave
to other texts.)

:(

-benjamin