[Review] Boost.Type Traits Extension by Frederic Bron
Dear All, This is the first day of the fast track review of Frédéric Bron's extensions to the Type Traits Library.This reviews will last until March 18th, 2011 under my management. All comments and reviews are very welcome. =========== What is it? =========== This extension adds 37 new traits corresponding to the following 37 operators: - binary: ==, !=,<,<=,>,>=, , +, -, *, /, %, +=, -=, *=, /=, %=, , &&, ||, ,&, |, ^,<<,>>,&=, |=, ^=,<<=,>>= - prefix: ++, --, +, -, !, ~, * - postfix: ++, -- Each trait can detect if the operator can be used with particular types and if needed, if the return type is convertible to some type. =================== Getting the library =================== The latest version can be downloaded by different ways: - from the vault with unix line ending: http://www.boostpro.com/vault/index.php?action=downloadfile&filename=type_traits.tar.bz2&directory=Extension& - from the vault with dos line ending: http://www.boostpro.com/vault/index.php?action=downloadfile&filename=type_traits-dos.tar.bz2&directory=Extension& - from the sandbox:http://svn.boost.org/svn/boost/sandbox/type_traits/ The entry point of the documentation is type_traits/libs/type_traits/doc/html/boost_typetraits/category/value_traits/operators.html The library has been tested with: - MSVC 8, 9, 10 on Windows, - g++ 4.4.5 on Linux, - intel 10.0 and 11.1 on Linux. To test the library, the simplest is to untar the headers in your boost include directory. For this, you can download the header part of the extension: - from the vault with unix line ending: http://www.boostpro.com/vault/index.php?action=downloadfile&filename=type_traits.headers_only.tar.bz2&directory=Extension& - from the vault with dos line ending: http://www.boostpro.com/vault/index.php?action=downloadfile&filename=type_traits.headers_only-dos.tar.bz2&directory=Extension&
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users- bounces@lists.boost.org] On Behalf Of Joel Falcou Sent: Monday, March 14, 2011 7:49 AM To: boost@lists.boost.org; boost-users@lists.boost.org; boost- announce@lists.boost.org Subject: [Boost-users] [Review] Boost.Type Traits Extension by Frederic Bron
I have only read the documentation but have a few minor comments on it. * I note that is does not use an automated system like Doxygen of producing the reference information. This seems to unfortunate, especially as there seem to be plans to change some names. I think we can be sure that there will be a fair number of glitches in the documentation when this happens :-( Although it is more work to start with (and does clutter the code - something that is made much less important by syntax coloring, so one can mentally ignore all the Doxygen comments) it does make it much, much easier to ensure that the code and the documentation of functions, classes... stay in step. I would like to see the whole library Doxygen fully commented (ask if you think I can help) - replacing much of the current reference text. * I note that I didn't get the Boost or navigation icons or fonts from the index.html sandbox site. * The previous PDF version is fine (but of course lacking the new operators). A new PDF version is extremely desirable (ask if you think I can help). * Some simpler (trivial even) examples might help newcomers to the library? The examples given are 'interesting' but quite complicated. * Floating point example(s) could refer to the Boost.Math library where type_traits are widely used? * A few items could be updated for the latest compilers like VC2010? has_nothrow_assign has no_throw_copy ... "Currently (May 2005) only Visual C++ 8 has the necessary compiler support to ensure that this trait "just works". " "Currently (May 2005) only Visual C++ 8 has the necessary compiler support to ensure that this trait "just works"." * a typo "Occationally the end user may need to provide their own specialization for one of the type traits ..." HTH Paul PS This is not a NO vote (in essence a YES seems a no-brainer) - I'd just like to see some improvements in the documentation. --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
* I note that is does not use an automated system like Doxygen of producing the reference information. This seems to unfortunate, especially as there seem to be plans to change some names. I think we can be sure that there will be a fair number of glitches in the documentation when this happens :-(
Although it is more work to start with (and does clutter the code - something that is made much less important by syntax coloring, so one can mentally ignore all the Doxygen comments) it does make it much, much easier to ensure that the code and the documentation of functions, classes... stay in step.
I would like to see the whole library Doxygen fully commented (ask if you think I can help) - replacing much of the current reference text.
Personally I wouldn't, sorry, but I'm still not completely sold on Doxygen :-(
* I note that I didn't get the Boost or navigation icons or fonts from the index.html sandbox site.
That will be a non-issue when merged to Trunk.
* The previous PDF version is fine (but of course lacking the new operators). A new PDF version is extremely desirable (ask if you think I can help).
Also a non-issue once it's merged to Trunk, as the type_traits PDF gets built for each release.
* Some simpler (trivial even) examples might help newcomers to the library? The examples given are 'interesting' but quite complicated.
* Floating point example(s) could refer to the Boost.Math library where type_traits are widely used?
* A few items could be updated for the latest compilers like VC2010?
has_nothrow_assign has no_throw_copy ...
"Currently (May 2005) only Visual C++ 8 has the necessary compiler support to ensure that this trait "just works". "
"Currently (May 2005) only Visual C++ 8 has the necessary compiler support to ensure that this trait "just works"."
Hehe, working on that now. In any case this is the "old" type_traits, not the extension under review. HTH, John.
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users- bounces@lists.boost.org] On Behalf Of John Maddock Sent: Thursday, March 17, 2011 11:25 AM To: boost-users@lists.boost.org Subject: Re: [Boost-users] [Review] Boost.Type Traits Extension by FredericBron
* I note that is does not use an automated system like Doxygen of producing the reference information.
I would like to see the whole library Doxygen fully commented (ask if you think I can help) - replacing much of the current reference text.
Personally I wouldn't, sorry, but I'm still not completely sold on Doxygen :-(
Well I agree that it isn't the perfect tool. (Doxygen gets confused with C++ and it's picky about linking comments to classes etc). As a user I find the current 'hand-written' alternatives deeply unsatisfactory. The bald synopsis just isn't good enough for the user. The synopsis just gives the class and function name and parameters types. But the user also needs to know what the parameters do, what the class or function does, what preconditions, what post conditions, what side effects, the "here be dragons" warnings, how to use it, examples ... Most of this information *has* to be hand-written - whether in plain text, or in comments of some sort. And it should all be in one place, not scattered. Only the Quickbook-Doxygen reference section seems to do this - *provided the actual code is fully commented*. So If you are going to suggest or produce a better or even the perfect tool - fine. But IMO much Boost current documentation just isn't good enough.
My other 'complaints' ...
Hehe, working on that now. In any case this is the "old" type_traits, not the extension under review.
OK fine - as long as you are on the job, I'm sure it will be fine :-) Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
On 3/17/2011 10:10 AM, Paul A. Bristow wrote:
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users- bounces@lists.boost.org] On Behalf Of John Maddock Sent: Thursday, March 17, 2011 11:25 AM To: boost-users@lists.boost.org Subject: Re: [Boost-users] [Review] Boost.Type Traits Extension by FredericBron
* I note that is does not use an automated system like Doxygen of producing the reference information.
I would like to see the whole library Doxygen fully commented (ask if you think I can help) - replacing much of the current reference text.
Personally I wouldn't, sorry, but I'm still not completely sold on Doxygen :-(
Well I agree that it isn't the perfect tool.
(Doxygen gets confused with C++ and it's picky about linking comments to classes etc).
As a user I find the current 'hand-written' alternatives deeply unsatisfactory.
The bald synopsis just isn't good enough for the user.
The synopsis just gives the class and function name and parameters types.
But the user also needs to know what the parameters do, what the class or function does, what preconditions, what post conditions, what side effects, the "here be dragons" warnings, how to use it, examples ...
Most of this information *has* to be hand-written - whether in plain text, or in comments of some sort.
And it should all be in one place, not scattered.
Only the Quickbook-Doxygen reference section seems to do this - *provided the actual code is fully commented*.
I use doxygen, but there is nothing keeping a quickbook author from writing hand-written comments instead. So it is incorrect to claim that "Only the Quickbook-Doxygen reference section seems to do this". Like you I still think doxygen is good enough since the long form of doxygen comments can be anything. But some people do find doxygen difficult, and I can understand that. I still think that good docs go beyond just using doxygen and need explanations in topics and good organization, and sometimes this is lacking in Boost docs. But John Maddock's documentation is always first-rate.
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users- bounces@lists.boost.org] On Behalf Of Edward Diener Sent: Thursday, March 17, 2011 2:56 PM To: boost-users@lists.boost.org Subject: Re: [Boost-users] [Review] Boost.Type Traits Extension by FredericBron
On 3/17/2011 10:10 AM, Paul A. Bristow wrote:
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users- bounces@lists.boost.org] On Behalf Of John Maddock Sent: Thursday, March 17, 2011 11:25 AM To: boost-users@lists.boost.org Subject: Re: [Boost-users] [Review] Boost.Type Traits Extension by FredericBron
* I note that is does not use an automated system like Doxygen of producing the reference information.
I would like to see the whole library Doxygen fully commented (ask if you think I can help) - replacing much of the current reference text.
Personally I wouldn't, sorry, but I'm still not completely sold on Doxygen :-(
Well I agree that it isn't the perfect tool.
(Doxygen gets confused with C++ and it's picky about linking comments to classes etc).
As a user I find the current 'hand-written' alternatives deeply unsatisfactory.
The bald synopsis just isn't good enough for the user.
The synopsis just gives the class and function name and parameters types.
But the user also needs to know what the parameters do, what the class or function does, what preconditions, what post conditions, what side effects, the "here be dragons" warnings, how to use it, examples ...
Most of this information *has* to be hand-written - whether in plain text, or in comments of some sort.
And it should all be in one place, not scattered.
Only the Quickbook-Doxygen reference section seems to do this - *provided the actual code is fully commented*.
I use doxygen, but there is nothing keeping a quickbook author from writing hand-written comments instead. So it is incorrect to claim that "Only the Quickbook-Doxygen reference section seems to do this".
Like you I still think doxygen is good enough since the long form of doxygen comments can be anything. But some people do find doxygen difficult, and I can understand that. I still think that good docs go beyond just using doxygen and need explanations in topics and good organization, and sometimes this is lacking in Boost docs. But John Maddock's documentation is always first-rate.
Indeed - the best - but I'm trying to encourage everyone to do as well, or better ;-) (I'm the nag behind AutoIndexing - to which challenge John has risen and conquered to my satisfaction - review upcoming). Just to be clear, I am NOT suggesting 'Standalone' Doxygen. I am suggesting generally using the Doxygen commands: \class \enum \file \brief \details \param \tparam \pre \post \returns \macro and perhaps \example \warning \remark \throws \see \typedef \var \version and even \deprecated ;-) Note that I said "Only the Quickbook-Doxygen reference section seems to get it should all be in one place, not scattered." It's the "one place, not scattered" that I think is the key here: this is what the Quickbook Doxygen Reference section does best. The discipline of thinking about which are suitable types of Doxygen comment listed above should discourage missing information (even if it means duplication). And the placing of documentation comments close to the code makes it easy to spot when these are out of step. As a user I still find that it is difficult to find even the things that I know exist (I remember that I wrote it!). Indexing is one aid, but it relies on the person producing the index, and in practice I find that searching a PDF is often the only way. Sorry to bang on about this, but too much documentation is written by authors who know too much, but is used by those who know too little :-) There are some good recent examples of improving Boost libraries in the pipeline. But IMO we still need to raise the bar for *user usability*. Paul (PS I have to admit that type_traits is not an ideal candidate for Doxygen comments on account of the considerable skulduggery with MACROS required to get it to work. So I can see that the effort in hiding this might be discouraging.)
On 3/18/2011 8:37 AM, Paul A. Bristow wrote:
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users- bounces@lists.boost.org] On Behalf Of Edward Diener Sent: Thursday, March 17, 2011 2:56 PM To: boost-users@lists.boost.org Subject: Re: [Boost-users] [Review] Boost.Type Traits Extension by FredericBron
On 3/17/2011 10:10 AM, Paul A. Bristow wrote:
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users- bounces@lists.boost.org] On Behalf Of John Maddock Sent: Thursday, March 17, 2011 11:25 AM To: boost-users@lists.boost.org Subject: Re: [Boost-users] [Review] Boost.Type Traits Extension by FredericBron
* I note that is does not use an automated system like Doxygen of producing the reference information.
I would like to see the whole library Doxygen fully commented (ask if you think I can help) - replacing much of the current reference text.
Personally I wouldn't, sorry, but I'm still not completely sold on Doxygen :-(
Well I agree that it isn't the perfect tool.
(Doxygen gets confused with C++ and it's picky about linking comments to classes etc).
As a user I find the current 'hand-written' alternatives deeply unsatisfactory.
The bald synopsis just isn't good enough for the user.
The synopsis just gives the class and function name and parameters types.
But the user also needs to know what the parameters do, what the class or function does, what preconditions, what post conditions, what side effects, the "here be dragons" warnings, how to use it, examples ...
Most of this information *has* to be hand-written - whether in plain text, or in comments of some sort.
And it should all be in one place, not scattered.
Only the Quickbook-Doxygen reference section seems to do this - *provided the actual code is fully commented*.
I use doxygen, but there is nothing keeping a quickbook author from writing hand-written comments instead. So it is incorrect to claim that "Only the Quickbook-Doxygen reference section seems to do this".
Like you I still think doxygen is good enough since the long form of doxygen comments can be anything. But some people do find doxygen difficult, and I can understand that. I still think that good docs go beyond just using doxygen and need explanations in topics and good organization, and sometimes this is lacking in Boost docs. But John Maddock's documentation is always first-rate.
Indeed - the best - but I'm trying to encourage everyone to do as well, or better ;-)
(I'm the nag behind AutoIndexing - to which challenge John has risen and conquered to my satisfaction - review upcoming).
Just to be clear, I am NOT suggesting 'Standalone' Doxygen.
I am suggesting generally using the Doxygen commands:
\class \enum \file \brief \details \param \tparam \pre \post \returns \macro
and perhaps
\example \warning \remark \throws \see \typedef \var \version
and even \deprecated ;-)
Note that I said
"Only the Quickbook-Doxygen reference section seems to get it should all be in one place, not scattered."
It's the "one place, not scattered" that I think is the key here: this is what the Quickbook Doxygen Reference section does best.
The discipline of thinking about which are suitable types of Doxygen comment listed above should discourage missing information (even if it means duplication).
And the placing of documentation comments close to the code makes it easy to spot when these are out of step.
As a user I still find that it is difficult to find even the things that I know exist (I remember that I wrote it!).
Indexing is one aid, but it relies on the person producing the index, and in practice I find that searching a PDF is often the only way.
Sorry to bang on about this, but too much documentation is written by authors who know too much, but is used by those who know too little :-)
There are some good recent examples of improving Boost libraries in the pipeline.
But IMO we still need to raise the bar for *user usability*.
I totall agree with you in general. But in Frederick Bron's case he really had to go with the method which type traits used in its documentation, since his work is an extension of type traits. I find what he write in the documentation to the type traits operators very adequate, since it really is not complicated to understand how they work.
Paul
(PS I have to admit that type_traits is not an ideal candidate for Doxygen comments on account of the considerable skulduggery with MACROS required to get it to work. So I can see that the effort in hiding this might be discouraging.)
In my variadic_macro_data library I did use doxygen to document the macros so I don't think having a library heavily oriented to macro use is an impediment to using doxygen. Of course if one is creating macros, to create code elements, its pretty hard to use doxygen to document those code elements themsleves as opposed to the macros.
AMDG On 03/18/2011 08:47 AM, Edward Diener wrote:
On 3/18/2011 8:37 AM, Paul A. Bristow wrote:
(PS I have to admit that type_traits is not an ideal candidate for Doxygen comments on account of the considerable skulduggery with MACROS required to get it to work. So I can see that the effort in hiding this might be discouraging.)
In my variadic_macro_data library I did use doxygen to document the macros so I don't think having a library heavily oriented to macro use is an impediment to using doxygen. Of course if one is creating macros, to create code elements, its pretty hard to use doxygen to document those code elements themsleves as opposed to the macros.
That kind of depends. If there's a 1-to-1 correspondence between the macro uses and the user-visible entities that they create, then you can just have doxygen expand the macros to something that looks sane in the documentation. The problem is when one macro defines multiple things that need to be documented independently. In Christ, Steven Watanabe
2011/3/17 Paul A. Bristow
* Some simpler (trivial even) examples might help newcomers to the library? The examples given are 'interesting' but quite complicated.
Are there examples in the docs? As far as I can see, there is an example on the implementation only. No examples on usage. They seem to be missing from the libs/type_traits/example directory as well. Regards, Joachim P.S.: Thanks to Frederic (and assisting operatorists) for this effort and good teamwork. The library extension looks pretty well to me :) -- Interval Container Library [Boost.Icl] http://www.joachim-faulhaber.de
Are there examples in the docs?
As far as I can see, there is an example on the implementation only. No examples on usage. They seem to be missing from the libs/type_traits/example directory as well.
There are use examples in the doc of the type trait library: http://www.boost.org/doc/libs/1_46_1/libs/type_traits/doc/html/boost_typetra... not in the extension. I could add one. Frédéric
* I note that is does not use an automated system like Doxygen of producing the reference information.
This would be a decision that would apply to the whole library. I am proposing only an extension and must follow what has been done before. But in the future this could be change if there is a consensus.
* Some simpler (trivial even) examples might help newcomers to the library? The examples given are 'interesting' but quite complicated.
I will think to add more simple examples. Frédéric
participants (7)
-
Edward Diener -
Frédéric Bron -
Joachim Faulhaber -
Joel Falcou -
John Maddock -
Paul A. Bristow -
Steven Watanabe