This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: documentation example for std::priority_queue


On Wed, Oct 27, 2004 at 02:10:56PM +0200, TheDD wrote:

> from [Bug libstdc++/18174]
> 
> i was asked to post it here:
> 
> -----------------------------------------
> 
> I just wanted to add an std::priority_queue usage example in the
> documentations,
> since it's not obvious when you don't know how tu use it.

Hi,

Thanks for the patch.

> In a general way, some examples should be present in the documentation
> i think.

This is a good idea in principle but I'm not sure adding them inline
with the function docs is ideal.  There are already plenty of books and
websites that show how to use the STL, especially such basic actions as
adding values to a container, accessing them again and then erasing them.

With the exception of one or two lines your example could apply to most
STL containers, there's not a lot specific to std::priority_queue. Using
a custom comparison function object is a general feature of STL
containers that should be covered once, not repeated for every container
type. Using a vector and constructing the priority_queue with a range
is another general container feature that is not specific to
priority_queue, it might be more  relevant to demonstrate use of the
push() member function. Finally, unless you compile and run the example
code it isn't clear how the priority_queue behaves - unless you're
already familiar with the concept of priority queues!

Considering all this, I would advocate something more like this, which
shows that the greatest values are at the front of the queue, and
demonstrates the push() member that is not common to all containers. It
also doesn't fature std::vector, which is not essential to understanding
priority_queue and only complicates the example. The assertions in this
code show you what to expect without having to even compile it:

    int main() {
      priority_queue<int> Q;
      Q.push(1);
      Q.push(4);
      Q.push(2);
      Q.push(8);
      Q.push(5);
      Q.push(7);
      
      assert(Q.size() == 6);

      assert(Q.top() == 8);
      Q.pop();

      assert(Q.top() == 7);
      Q.pop();

      assert(Q.top() == 5);
      Q.pop();

      assert(Q.top() == 4);
      Q.pop();

      assert(Q.top() == 2);
      Q.pop();

      assert(Q.top() == 1);
      Q.pop();

      assert(Q.empty());
    }

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

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.

> Since there isn't an "html" target in the root Makefile of gcc i
> didn't check
> for validity of the patch, but i think it's ok.

The doxygen docs are built using the run_doxygen script in the libstdc++
source tree (libstdc++-v3/docs/doxygen/run_doxygen). This is necessary
because some extra kluges are needed to fix up the generated docs, and
as I understand it doing this from a Makefile is not convenient right
now.

> $ uuencode priority_queue-3.4.1.patch.uu < priority_queue-3.4.1.patch

> for easy viewing (i don't know if posting the patch in plain text is
> ok because
> of space breaking):

If you attach it, rather than pasting it in, line-breaking shouldn't
happen (but that probably depends on your mailer).

> @@ -101,7 +101,63 @@
>     *  Members not found in "normal" containers are @c container_type,
>     *  which is a typedef for the second Sequence parameter, and @c
> push and
>     *  @c pop, which are standard %queue/FIFO operations.
> -  */
> +   *
> +   *  \b Example:
> +   *  \code
> +   *  #include <iostream>
> +   *  #include <vector>
> +   *  #include <queue>
[snip]

Finally, your doxygen markup uses \this form not @this form - IIRC the
rest of the docs use @this fairly consistently.

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).
 
jon

-- 
There are only 10 types of people in the world -
Those who understand binary, and those who don't.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]