From an user to developers
Hello, I am an user, and I am currently reviewing all the Boost libraries. But for a common user, some needs are not satisfied in the libraries descriptions. The Boost organization should compel the libraries authors to put in their documentation : 1. the history of all releases, with notes for each release 2. the motivation of their library 3. when they offer services similar to the ones provided by the STL, why did they feel the need to complete it, and what are the differences 3. for the relevant libraries, their status regarding the new features of C++11 (are they obsolete ? do they remain some differences ? ex : Array, Chrono, DateTime), especially the ones related to TR1 An homogeneous structure for the documentation would be welcome.
On 8 June 2012 17:01, Oodini <svdbg@free.fr> wrote:
Hello,
I am an user, and I am currently reviewing all the Boost libraries.
But for a common user, some needs are not satisfied in the libraries descriptions.
The Boost organization should compel the libraries authors to put in their documentation :
1. the history of all releases, with notes for each release
You mean a changelog per library?
2. the motivation of their library
Do you have any examples handy?
3. when they offer services similar to the ones provided by the STL, why did they feel the need to complete it, and what are the differences
Same, examples?
3. for the relevant libraries, their status regarding the new features of C++11 (are they obsolete ? do they remain some differences ? ex : Array, Chrono, DateTime), especially the ones related to TR1
AFAIK, there is no such concept as obsolete Boost library if confronted with C++ standard libraries. The fact that C++ std has got std::shared_ptr does not make boost::shared_ptr deprecated. boost::shared_ptr stays here and will be offered as an alternative implementation, same boost::array and similar.
An homogeneous structure for the documentation would be welcome.
I second that, it is even annoying to have multiple formats and documenting technologies involved, but I have lost hope on that front. There has been severe amount of discussion on boost-docs (e.g. see the thread about Sphinx integration http://lists.boost.org/boost-docs/2011/09/index.php) Boost is huge and it is impractical to ask developers to follow single convention of formats and tools, fight against personal preferences of developers, etc. So, I have taken that point. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
Le 08/06/2012 18:57, Mateusz Loskot a écrit :
1. the history of all releases, with notes for each release
You mean a changelog per library?
Yes.
2. the motivation of their library
Do you have any examples handy ?
A good example is Boost.Lambda : http://www.boost.org/doc/libs/1_49_0/doc/html/lambda/s03.html#id2374031 Boost.Iostreams could do better... So as Boost.Locale.
3. when they offer services similar to the ones provided by the STL, why did they feel the need to complete it, and what are the differences
Same, examples?
All the TR1 librairies. Boost.Locale, shared_ptr...
3. for the relevant libraries, their status regarding the new features of C++11 (are they obsolete ? do they remain some differences ? ex : Array, Chrono, DateTime), especially the ones related to TR1
AFAIK, there is no such concept as obsolete Boost library if confronted with C++ standard libraries.
Is this an ideological point of view ?
The fact that C++ std has got std::shared_ptr does not make boost::shared_ptr deprecated.
What makes one use boost_shared_ptr instead of std::shared_ptr ? Does he have to read all the doc to find out the differences ? Does he have to do same for EACH library conflicting with C+11 ? Because there are many ones : Array Bind Chrono Enable If Foreach Function Functional/Hash Lambda Lexical Cast ... Static Assert Thread ...
boost::shared_ptr stays here and will be offered as an alternative implementation, same boost::array and similar.
I asked Nicolas Josuttis about Array, and here what he replied to me : "Yes, boost.array is obsolete with C++11. Will see what I can do to describe it (limited time currently)."
Boost is huge and it is impractical to ask developers to follow single convention of formats and tools, fight against personal preferences of developers, etc. So, I have taken that point.
Well, Boost appears to me as a nice label for a library. Maybe the developpers could do an effort.
On 10 June 2012 13:07, Stéphane Vandenbogaerde <svdbg@free.fr> wrote:
Le 08/06/2012 18:57, Mateusz Loskot a écrit :
1. the history of all releases, with notes for each release
You mean a changelog per library?
Yes.
There is a pretty good history overview per version published at http://www.boost.org/users/history/ Plus, there are logs in SVN.
2. the motivation of their library
Do you have any examples handy ?
A good example is Boost.Lambda : http://www.boost.org/doc/libs/1_49_0/doc/html/lambda/s03.html#id2374031
I meant libraries which lack of such section. AFAIK, motivation section is a common convention in Boost, so if any library lacks, I think bug report on Trac would be handy.
3. when they offer services similar to the ones provided by the STL, why did they feel the need to complete it, and what are
the differences
Same, examples?
All the TR1 librairies. shared_ptr...
IMO, it is purpose of the C++03, C++ TR1 and C++11 documents to reveal differences. "Read the Code, Luke"
Boost.Locale
It is not a library specified in the C++ standard or TRs.
3. for the relevant libraries, their status regarding the new features of C++11 (are they obsolete ? do they remain some differences ? ex : Array, Chrono, DateTime),
especially the ones related to TR1
AFAIK, there is no such concept as obsolete Boost library if confronted with C++ standard libraries.
Is this an ideological point of view ?
Not at all.
The fact that C++ std has got std::shared_ptr does not make boost::shared_ptr deprecated.
What makes one use boost_shared_ptr instead of std::shared_ptr ?
No availability of C++11 compiler. Plus, "[boost::shared_ptr] implementation conforms to the TR1 specification", but std::shared_ptr is C++11 implementation. Generally, to be on safe side, if your code works with the boost::shared_ptr/TR1, it should work with the std::shared_ptr/C++11 too, but not necessarily the other way around.
Does he have to read all the doc to find out the differences ?
and the C++ standard, and TR1.
Does he have to do same for EACH library conflicting with C+11 ?
There are no conflicts between Boost and C++ std. Boost, among others, provide a distinct implementation of libraries specified in C++ standard(s) or TRs.
boost::shared_ptr stays here and will be offered as an alternative implementation, same boost::array and similar.
I asked Nicolas Josuttis about Array, and here what he replied to me :
"Yes, boost.array is obsolete with C++11. Will see what I can do to describe it (limited time currently)."
IMHO, you have misinterpreted his words. I believe, you can't expect Boost project to remove Boost.Array from its source code for as long as there are users who 1) want to use Boost.Array Boost libraries 2) don not want or can not use C++11 compiler
Boost is huge and it is impractical to ask developers to follow single convention of formats and tools, fight against personal preferences of developers, etc. So, I have taken that point.
Well, Boost appears to me as a nice label for a library. Maybe the developpers could do an effort.
No comments. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
Oodini wrote:
I am an user, and I am currently reviewing all the Boost libraries.
Welcome to Boost!
The Boost organization should compel the libraries authors to put in their documentation :
1. the history of all releases, with notes for each release
There are per-library release notes managed at the release level visible on boost.org.
2. the motivation of their library
I agree that this is useful. It can be difficult to grasp the value of a library when first reading about it.
3. when they offer services similar to the ones provided by the STL, why did they feel the need to complete it, and what are the differences
Any apparent duplication of the standard library should be discussed.
3. for the relevant libraries, their status regarding the new features of C++11 (are they obsolete ? do they remain some differences ? ex : Array, Chrono, DateTime), especially the ones related to TR1
There are a great many new C++11 features. It would be inordinately burdensome to expect each library maintainer to indicate which of those features have been used, won't be used, etc. Where a library provides a C++03 equivalent for a C++11 feature, it does make sense to note the differences.
An homogeneous structure for the documentation would be welcome.
Increasingly, there is commonality among the various libraries. Older libraries predate the current documentation mechanisms, so would be nontrivial to update. Some libraries are documented with standardization in mind, and while I understand the motivation for the resulting standard-like documentation format, it isn't accessible to normal users. Most of these issues can be addressed, however, by filing bugs and supplying patches. Most of the maintainers would apply, if not welcome, useful documentation improvements. _____ Rob Stewart robert.stewart@sig.com Software Engineer using std::disclaimer; Dev Tools & Components Susquehanna International Group, LLP http://www.sig.com ________________________________ IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.
Le 08/06/2012 19:06, Stewart, Robert a écrit :
1. the history of all releases, with notes for each release
There are per-library release notes managed at the release level visible on boost.org.
Yes, but when you're unterested in a specific library, it is tedious to check each Boost release, even if the concerned library hasn't been updated in this Boost release.
2. the motivation of their library
I agree that this is useful. It can be difficult to grasp the value of a library when first reading about it.
Great. I have been understood. :-)
There are a great many new C++11 features. It would be inordinately burdensome to expect each library maintainer to indicate which of those features have been used, won't be used, etc.
They cold at least say something like that : "Since the C++11 release, some features may be obsolete. I'll update the documentation when I'll have time. Feel free to help me to check each feature against C++11". Maybe a wiki would be useful.
Increasingly, there is commonality among the various libraries. Older libraries predate the current documentation mechanisms, so would be nontrivial to update. Some libraries are documented with standardization in mind, and while I understand the motivation for the resulting standard-like documentation format, it isn't accessible to normal users.
Most of these issues can be addressed, however, by filing bugs and supplying patches. Most of the maintainers would apply, if not welcome, useful documentation improvements.
I think an unofficial wiki wuuld be useful in this purpose. The official maintainer could then pick the info when he has time to update the doc.
Oodini wrote:
Hello,
I am an user, and I am currently reviewing all the Boost libraries.
I am a user also.
But for a common user, some needs are not satisfied in the libraries descriptions.
This is an understatement.
The Boost organization should compel the libraries authors to put in their documentation :
1. the history of all releases, with notes for each release 2. the motivation of their library 3. when they offer services similar to the ones provided by the STL, why did they feel the need to complete it, and what are the differences
many library documents have a section called "rationale" for this
3. for the relevant libraries, their status regarding the new features of C++11 (are they obsolete ? do they remain some differences ? ex : Array, Chrono, DateTime), especially the ones related to TR1
This is a problem. What happens with a library from 10 years ago? Is being a library developer a life sentence? I understand the problem but I don't see definitive solution. The only way we "compel" authors to put things in a documentation is through the review/approval process. It's better than nothing but has not been enough to improve documentation.
An homogeneous structure for the documentation would be welcome.
I understand the motivation - but again - lot's of problems in practice. Here is my take on the above. a) In general, C++ Library Documentation is generally very poor and hard to understand. It suffers from all the above mentioned problems. Boost library documentation is better than most - but still very uneven quality between libraries. b) Although many believe that there is some sort of "formal" standard for reference documentation there is not. There is a wide variation among developers on what should be in documentation and what should not be. Suggestions for documentation formats and content vary widely. The boost page on this subject is very hard to find. c) The requirements for documentation varies amongst the different types of things being documentated: types, functions, classes, concepts templates, etc. d) The fact that is extremely easy to identify poor documentation in no way makes it easier to write good documentation. e) more pages of documentation doesn't necessariliy mean that the the documentation is better. One thing I would suggest for the real user is to buy a few books: a) A good C++ reference - I use The C++ programming language - Stroustrup b) All the books by Scott Meyers b) If you're going to use templates - C++ Templates - Vandevoorde & Josuttis c) If you're going to even look at mpl - C++ Template Metaprogramming - Abrahams & Gurtovoy d) If you're going to use STL -STL tutorial and reference - Musser & Saini e) If you're going to use Boost - The Boost C++ Libraries (or similar book) - Boris Schäling I realize that this sounds like a really dumb suggestion. There are two facts which jump out at me: a) I probably consult at least one of these books every single day. b) as a contract developer, I work at various companies. 1) I have never seen more than one of these books at any customer site. 2) I have had to purchase any C++ book out of my own funds. So, there is much, much more to this problem than your question would suggest. You will all be hearing much, much more from me on this topic in the near future. Robert Ramey
participants (5)
-
Mateusz Loskot -
Oodini -
Robert Ramey -
Stewart, Robert -
Stéphane Vandenbogaerde