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.