[convert] incomplete reference documentation
Hi, 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? Thanks, Vicente
On 4/5/2011 7:18 PM, Vicente BOTET wrote:
Hi,
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?
Do you have the latest version from the Vault ? Don't you think you should say what you feel is incomplete about it ?
Message du 06/04/11 03:44 De : "Edward Diener" A : boost@lists.boost.org Copie à : Objet : Re: [boost] [convert] incomplete reference documentation
On 4/5/2011 7:18 PM, Vicente BOTET wrote:
Hi,
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?
Do you have the latest version from the Vault ?
I downloaded it yesterday. The doc has this date Last revised: March 02, 2011 at 22:33:53 GMT
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. Best, Vicente
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Vicente BOTET Sent: Wednesday, April 06, 2011 8:09 AM To: boost@lists.boost.org Subject: Re: [boost] [convert] incomplete reference documentation
Message du 06/04/11 03:44 De : "Edward Diener" A : boost@lists.boost.org Copie à : Objet : Re: [boost] [convert] incomplete reference documentation
On 4/5/2011 7:18 PM, Vicente BOTET wrote:
Hi,
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?
Do you have the latest version from the Vault ?
I downloaded it yesterday. The doc has this date Last revised: March 02, 2011 at 22:33:53 GMT
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.
I've ticked the DoxyWizard WARN_IF_UNDOCUMENTED, WARN_IF_DOC_ERROR AND WARN_NO_PARAMDOC options and sent the warning to a WARN_LOGFILE. (And similarly in the jamfile) If you see that the file is not empty, you know there is more to do :-( And it lists the TODOs. But it does get very tedious if you come along to do it afterwards:-(( So I've written "note to self" to do Doxygen comments when writing the code in the first place (but that is distracting). No such thing as a free lunch! Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
On 4/6/2011 3:09 AM, Vicente BOTET wrote:
Message du 06/04/11 03:44 De : "Edward Diener" A : boost@lists.boost.org Copie à : Objet : Re: [boost] [convert] incomplete reference documentation
On 4/5/2011 7:18 PM, Vicente BOTET wrote:
Hi,
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?
Do you have the latest version from the Vault ?
I downloaded it yesterday. The doc has this date Last revised: March 02, 2011 at 22:33:53 GMT
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.
I think in the doc only tha main class is documented in the reference section because the author decided the other classes were implementation details and put them in the detail subdirectory. In my own libraries I do not document anything in the detail subdirctory and I think that is the standard practice.
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.
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
----- Original Message ----- From: "Vicente BOTET" <vicente.botet@wanadoo.fr> ... 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.
I've uploaded 1.05 where I managed to get better Reference-related results. Namely, convert and result classes are represented there. Still, it looks ridiculously little -- 3 overloads of convert::from and 2 functions in result. I am somewhat skeptical of the value it adds. The specialized convertor implementations are still hidden as I consider those implementation details and do not want users to see those. Best, V.
Message du 07/04/11 11:38 De : "Vladimir Batov" A : boost@lists.boost.org Copie à : Objet : Re: [boost] [convert] incomplete reference documentation
----- Original Message ----- From: "Vicente BOTET" ... 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.
I've uploaded 1.05 where I managed to get better Reference-related results. Namely, convert and result classes are represented there. Still, it looks ridiculously little -- 3 overloads of convert::from and 2 functions in result. I am somewhat skeptical of the value it adds. The specialized convertor implementations are still hidden as I consider those implementation details and do not want users to see those.
I can accept that you want to hide the converter class. But you need to state in the documentation that the result of the from operation is a implementation defined class which is convertible to Target and provide in addition other operations which must be stated explicitly. Otherwise how the user can know that the following is correct using namespace boost::conversion::parameter; direction dir = convert::from(str, up_dir)(throw_ = true); or int i = convert::from(hex_str) >> std::hex; string si = convert::from(i)
std::showbase >> std::uppercase >> std::hex;
Best, Vicente
Vicente BOTET <vicente.botet <at> wanadoo.fr> writes:
I can accept that you want to hide the converter class. But you need to state in the documentation that the result of the from operation is a implementation defined class which is convertible to Target and provide in addition other operations which must be stated explicitly.
Vicente, Yes, I agree, it's a valid point. I added another converter-related section into the documentation; moved all the implementation files from boost/convert/detail to boost/convert as as you mentioned converters' interface needs to be more accessible to the users. Sadly, Doxygen was not able to pick up those additional classes and interfaces to include those into the Reference section. I am still looking into it. For now, the mentioned changes have been uploaded into the Vault as boost-string-convert.zip ver. 1.06. Thanks, V.
participants (4)
-
Edward Diener -
Paul A. Bristow -
Vicente BOTET -
Vladimir Batov