RE: [boost] Adding a generic list manipulator - documentation

From: Paul A. Bristow (boost_at_[hidden])
Date: 2003-04-23 03:21:45

| -----Original Message-----
| From: boost-bounces_at_[hidden]
| [mailto:boost-bounces_at_[hidden]]On Behalf Of Reece Dunn
| Sent: Thursday, April 17, 2003 2:53 PM
| To: boost_at_[hidden]
| Subject: Re: [boost] Adding a generic list manipulator
|
|
| [documentation]:
|
Shows much promise, but

1  code examples are conventionally (and helpfully) in monospaced.  My favourite
is Lucida Console.  Doesn't boost.css provide this?

2  Your potential users are busy, and not all expert, so over-commenting is
better than under.  For example, how about?

std::vector< int > v( 4);  // Construct a vector of known size 4.
std::generate( v.begin(), v.end(), std::rand ); // Fill all container with
randoms.
std::cout << boost::io::formatlist( v ); // Output all container.
// Outputs: {101, 4, 33, 9}

3  Examples are the most useful.  And I find placing the output as a comment is
most helpful (to me when I read my examples some time later!).

std::cout << boost::io::formatlist( v ); // Outputs: {101 | 4 | 33 | 9}

4 Using MSVC at least it is also very easy to snapshot the output from a console
application and append it as a lng C-style comment

/*

Output is:

{101 | 4 | 33 | 9}

Press any key to continue

*/

5  Since the whole point is that one can use this for nearly any container, help
users who 'just want it output' by providing an example of their container, or
near.  (Also give a legalistic Standardese definition of requirements: begin and
end iterators must exist...).

Paul

Paul A Bristow, Prizet Farmhouse, Kendal, Cumbria, LA8 8AB  UK
[phone]   Mobile [phone]
Mobile mailto:pabristow_at_[hidden]
mailto:pbristow_at_[hidden]

PS I Hope to look at the code too soon.