[doc] General Boost documentation suggestion
This is an impassioned plea for all library developers writing documentation about classes and/or functions ( including class templates and function templates ). Please, please put somewhere in the low-level description/explanation of that class and function both the full namespace it is in and the header file which must be included. Numerous times, using the functionality of an otherwise wonderful Boost library, I have had to hunt through the rest of that library's documentation to find the full namespace and header file which must be included in order to correctly use a particular function or class. This is irritatingly time consuming and can be remedied in all cases by the suggestion above. Thank you !
on Sun Aug 17 2008, Edward Diener <eldiener-AT-tropicsoft.com> wrote:
This is an impassioned plea for all library developers writing documentation about classes and/or functions ( including class templates and function templates ). Please, please put somewhere in the low-level description/explanation of that class and function both the full namespace it is in and the header file which must be included.
Numerous times, using the functionality of an otherwise wonderful Boost library, I have had to hunt through the rest of that library's documentation to find the full namespace and header file which must be included in order to correctly use a particular function or class. This is irritatingly time consuming and can be remedied in all cases by the suggestion above.
Thank you !
Hi Edward, Please enter tickets into our trac when that happens to you, or most opportunities to make corrections will surely be overlooked. Thanks, -- Dave Abrahams BoostPro Computing http://www.boostpro.com
Edward Diener wrote:
Numerous times, using the functionality of an otherwise wonderful Boost library, I have had to hunt through the rest of that library's documentation to find the full namespace and header file which must be included in order to correctly use a particular function or class. This is irritatingly time consuming and can be remedied in all cases by the suggestion above.
I'd second that. Of course it's quite possible I may be guilty of the above as well.... John.
John Maddock wrote:
Edward Diener wrote:
Numerous times, using the functionality of an otherwise wonderful Boost library, I have had to hunt through the rest of that library's documentation to find the full namespace and header file which must be included in order to correctly use a particular function or class. This is irritatingly time consuming and can be remedied in all cases by the suggestion above.
I'd second that. Of course it's quite possible I may be guilty of the above as well....
You are occasionally, but so are most Boost developers in the reference documentation for a library. It would be real nice if, as a generally agreed documentation convention for Boost libraries, the #include file and namespace were listed separately at the top of each detailed explanation in a library's reference documentation. I have posted this as a Trac item, as Dave suggested.
participants (3)
-
David Abrahams -
Edward Diener -
John Maddock