[Home]Documentation - Program Options Library

BOOST WIKI | RecentChanges | Preferences | Page List | Links List

Difference (from prior major revision) (minor diff)

Added: 12a13,17
I agree. However, I probably can't do that right now. If the library is accepted, I plan to convert documentation to BoostBook?
format, which will make adding example output simpler. Frankly, I don't know the right way to do this in Doxygen.

- People/Vladimir Prus


Added: 49a55,58
Done in revision 180.

- People/Vladimir Prus


Changed: 84c93,97


First part done in revision 180. I'll document "--" at the same time as adding example input and output.

- People/Vladimir Prus




This page is for discussion of problems in the Boost Program_options Library documentation (library is currently under review)

Back to program options library pages


Show sample program output

When code is given for an example program, after the code, give examples of using the program, along with the expected output.

    - People/Chuck Messenger

I agree. However, I probably can't do that right now. If the library is accepted, I plan to convert documentation to BoostBook? format, which will make adding example output simpler. Frankly, I don't know the right way to do this in Doxygen.

    - People/Vladimir Prus


Remove unnecessary template parameters

The sample code is unnecessarily verbose, e.g.:

        desc.add_options()
            ("help", "", "produce help message")
            ("verbose", parameter<bool>("[yes/no]", &verbose), "verbose output")
            ("magic", parameter<int>("value", &magic), "magic value for the program")
            ("word", parameter<string>("whatever", &word), "internal parameter")
            ("numbers", parameter< vector<int> >("list+", &v), "a list of numbers")
            ("path,I", parameter< vector<string> >("list", &sv), "some path")
            ;

it isn't necessary to explicitly parameterize parameter<> -- you can do:

        desc.add_options()
            ("help", "", "produce help message")
            ("verbose", parameter("[yes/no]", &verbose), "verbose output")
            ("magic", parameter("value", &magic), "magic value for the program")
            ("word", parameter("whatever", &word), "internal parameter")
            ("numbers", parameter("list+", &v), "a list of numbers")
            ("path,I", parameter("list", &sv), "some path")
            ;

(at least with gcc3.2.2...)

Why make it look harder/worse than it is? Well, I can imagine a good reason why: to emphasize that these are template functions. But still, normal usage shouldn't use unnecessary template parameters. The sample code is liable to be copied into peoples' own code, as a starting point. So, it should be exemplary.

    - People/Chuck Messenger

Done in revision 180.

   - People/Vladimir Prus


Explain role of "+" in add_options()

The following code is shown (second sample program):

        //  The 'numbers' option can take several parameters, like
        //  --numbers 1 2 3 4
        ("numbers", parameter< vector<int> >("list+", &v), "a list of numbers")

        // Only one value can be specified per occurence of "-I", but
        // values from all occurences will be stored in one vector.
        ("path,I", parameter< vector<string> >("list", &sv), "some path")

Some experimentation shows the "+" makes multiple arguments allowable. This should be spelled out, perhaps like this:

        //  Due to the "+", the 'numbers' option can take several parameters, like
        //  --numbers 1 2 3 4

Also, via experimentation, the "--" argument ends a list, e.g.

    $ test2 --numbers 1 2 3 -- arg1 

Without the --, "arg1" is treated as a number, rather than an argument. This should be demonstrated in the documentation, just after the sample program.

    - People/Chuck Messenger

First part done in revision 180. I'll document "--" at the same time as adding example input and output.

    - People/Vladimir Prus



BOOST WIKI | RecentChanges | Preferences | Page List | Links List
Edit text of this page | View other revisions
Last edited May 21, 2003 11:04 pm (diff)
Search:
Disclaimer: This site not officially maintained by Boost Developers