Re: [boost] [convert] incomplete reference documentation

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.

Vicente,

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?

Best,
Vladimir.