Message du 07/04/11 00:17 De : "Vladimir Batov" A : boost@lists.boost.org Copie à : Objet : Re: [boost] [convert] incomplete reference documentation
Vicente BOTET 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.
Hi, recall my words in the first post "the reference documentation is incomplete and not ready for review".
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.
It is quite odd to review a library that has no reference documentation, as sometimes we need to check this reference documentation to check if we understand the tutorial correctly.
Does it alleviate your Reference-related concerns?
My concerns are more before the review than after. If you want to facilitate the task of the reviewers, and as the interface is not too big, I suggest you to document it by directly with quickbook before the review until you are able to have a correct reference documentation with doxygen. Best, Vicente