Subject: Re: [boost] [convert] incomplete reference documentation
From: Vladimir Batov (vbatov_at_[hidden])
Date: 2011-04-06 18:15:50
> Vicente BOTET <vicente.botet <at> wanadoo.fr> writes:
> > > I was taking a look at the documentation and it seems to me that the
reference documentation is incomplete
> and not ready for review. Do you plan to complete it before review?
> > Don't you think you should say what you feel is incomplete about it ?
> Well, I would prefer the author checks it. I suspect that the documentation is
> generated with doxygen, and
> we must be quite careful to ensure all the public parts are documented.
Thank you for your input. It's much appreciated and my apologies for the delay
replying. As you suggested I checked the documentation again. The library
documentation is in the standard location -- libs/convert/doc/html -- and is
overwhelmingly generated by QuickBook (which is awesome BTW) rather than with
Doxygen. Indeed, the Reference section of the documentation is generated with
Doxygen and it's quite terse ;-). However, I am far from the view that it is
"not ready for review" as apart from the Reference section there are 13 more
sections where I tried to discuss and explain the library purpose, usage, etc.
in a friendlier-than-reference format. Still, I do have to acknowledge that the
small part of the documentation -- the Doxygen-generated Reference section -- is
far from complete. And the Index section is empty as the index-generating tools
are not part of the official Boost distribution.
As for the Reference section, then although I do use Doxygen at work I had
difficulties getting good results as part QuickBook-based generation. So, as I
did not see it as a show-stopper I decided to attend to it after the review (if
that review is positive of course). In fact, in all honesty I might be even
reluctant having that Reference section as on its own it will not tell anything
due to very minimal API (simple convert::from is sufficient for the majority of
applications). On the other hand after reading the rest of the documentation I
feel there will be little need for the Reference section. That said, I'd like to
re-iterate that if the outcome is positive, I'll be fixing all the places
needing attention the Reference section included.
Does it alleviate your Reference-related concerns?
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk