Re: [boost] [convert] incomplete reference documentation

Subject: Re: [boost] [convert] incomplete reference documentation
From: Vicente BOTET (vicente.botet_at_[hidden])
Date: 2011-04-07 01:46:44

> Message du 07/04/11 00:17
> De : "Vladimir Batov" 
> A : boost_at_[hidden]
> 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