hi all, i've reported an issue before that boost.test in the release branch is pretty broken. *all* tests of the boost.heap testsuite segfault like this: --Program received signal SIGSEGV, Segmentation fault. 0x00000000005f4975 in boost::unit_test::test_suite::add (this=0x8cefa0, tu=0x9, expected_failures=0, timeout=0) at ../../../boost/test/impl/unit_test_suite.ipp:139 139 m_members.push_back( tu->p_id ); (gdb) bt #0 0x00000000005f4975 in boost::unit_test::test_suite::add (this=0x8cefa0, tu=0x9, expected_failures=0, timeout=0) at ../../../boost/test/impl/unit_test_suite.ipp:139 #1 0x00000000005fda9c in boost::unit_test::ut_detail::test_init_caller::operator() (this=0x8d4e08) at ../../../boost/test/impl/framework.ipp:96 #2 0x00000000006031a2 in boost::unit_test::ut_detail::invoker<int>::invoke<boost::unit_test::ut_detail::test_init_caller> (this=0x7fffffffc36f, f=...) at ../../../boost/test/utils/callback.hpp:42 #3 0x0000000000603071 in boost::unit_test::ut_detail::callback0_impl_t<int, boost::unit_test::ut_detail::test_init_caller>::invoke (this=0x8d4e00) at ../../../boost/test/utils/callback.hpp:89 #4 0x000000000060e03d in boost::unit_test::callback0<int>::operator() (this=0x7fffffffcfc0) at ../../../boost/test/utils/callback.hpp:118 #5 0x000000000060de8a in boost::detail::do_invoke<boost::scoped_ptr<boost::detail::translate_exception_base>, boost::unit_test::callback0<int> > (tr=..., F=...) at ../../../boost/test/impl/execution_monitor.ipp:281 #6 0x000000000060d1a8 in boost::execution_monitor::catch_signals (this=0x7fffffffcfd0, F=...) at ../../../boost/test/impl/execution_monitor.ipp:885 #7 0x000000000060d262 in boost::execution_monitor::execute (this=0x7fffffffcfd0, F=...) at ../../../boost/test/impl/execution_monitor.ipp:1211 #8 0x00007ffff7b0bf33 in boost::unit_test::framework::init (init_func=0x4e3f30 <init_unit_test()>, argc=1, argv=0x7fffffffd198) at ../../../boost/test/impl/framework.ipp:268 #9 0x00007ffff7b22267 in boost::unit_test::unit_test_main (init_func=0x4e3f30 <init_unit_test()>, argc=1, argv=0x7fffffffd198) at ../../../boost/test/impl/unit_test_main.ipp:177 #10 0x00000000004e3f62 in main (argc=1, argv=0x7fffffffd198) at ../../../boost/test/unit_test.hpp:59 -- boost.test in trunk works fine, though ... i wonder, will it eventually be merged to release? tim
Tim Blechmann <tim <at> klingt.org> writes:
hi all,
i've reported an issue before that boost.test in the release branch is pretty broken. *all* tests of the boost.heap testsuite segfault like this:
There were no changes in boost release for several years. Can you wor karound it for now?
boost.test in trunk works fine, though ... i wonder, will it eventually be merged to release?
I lost my work on new docs unfortunately to broken laptop, still trying to revive it, but I'm lacking time to really get to it. Maybe this can give me another reason to finally push it out. Gennadiy
hi,
i've reported an issue before that boost.test in the release branch is pretty broken. *all* tests of the boost.heap testsuite segfault like this:
There were no changes in boost release for several years. Can you wor karound it for now?
are you sure? this would imply that the boost.heap testsuite was always broken on release, though i'm pretty sure that wasn't the case. the only workaround i can think of, is to get rid of boost.test, though i don't have too much time to spend on this atm ...
boost.test in trunk works fine, though ... i wonder, will it eventually be merged to release?
I lost my work on new docs unfortunately to broken laptop, still trying to revive it, but I'm lacking time to really get to it. Maybe this can give me another reason to finally push it out.
i see ... fwiw, testing is a rather important part, especially for the release branch ... so it would be great if you could merge it, soon ... thanks, tim
Tim Blechmann <tim <at> klingt.org> writes:
hi,
i've reported an issue before that boost.test in the release branch is pretty broken. *all* tests of the boost.heap testsuite segfault like
this:
There were no changes in boost release for several years. Can you wor
karound
it for now?
are you sure? this would imply that the boost.heap testsuite was always broken on release, though i'm pretty sure that wasn't the case.
I did not make any chnages. You can check a release branch. Unless something changes in a test setup (new compiler/platform/compilation options). Gennadiy
[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <loom.20130802T232929-478@post.gmane.org> thusly:
I lost my work on new docs unfortunately to broken laptop, still trying to revive it, but I'm lacking time to really get to it.
I wouldn't bother reviving your work on new docs since I am completely rewriting them and am almost finished. -- "The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline> The Computer Graphics Museum <http://computergraphicsmuseum.org> The Terminals Wiki <http://terminals.classiccmp.org> Legalize Adulthood! (my blog) <http://legalizeadulthood.wordpress.com>
Richard <legalize+jeeves <at> mail.xmission.com> writes:
[Please do not mail me a copy of your followup]
boost <at> lists.boost.org spake the secret code <loom.20130802T232929-478 <at> post.gmane.org> thusly:
I lost my work on new docs unfortunately to broken laptop, still trying to revive it, but I'm lacking time to really get to it.
I wouldn't bother reviving your work on new docs since I am completely rewriting them and am almost finished.
Do you follow trunk or release state of Boost.Test? Gennadiy
[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <loom.20130807T214918-704@post.gmane.org> thusly:
boost <at> lists.boost.org spake the secret code <loom.20130802T232929-478 <at> post.gmane.org> thusly:
I lost my work on new docs unfortunately to broken laptop, still trying to revive it, but I'm lacking time to really get to it.
I wouldn't bother reviving your work on new docs since I am completely rewriting them and am almost finished.
Do you follow trunk or release state of Boost.Test?
I've been working based on trunk, but could easily adapt to another branch if that is the preferred place. I posted a call for reviewers on May 1 and am on snapshot 6 right now. Details: - I pull trunk as a mercurial repo - I create my changes as a mercurial patch queue patch on this repo - I version control my patches and push them to another machine to guard against accidental data loss - I periodically pull trunk from SVN and rebase my patches on top of that. - Everything is written in Quickbook - It is a true rewrite, not an edit of existing docs - Some Quickbook annotations are added to header files to briefly summarize the major classes/functions that a user of Boost.Test is likely to care about: test_unit, test_case, test_suite, master_test_suite_t, test_observer, unit_test_log_t, unit_test_log_formatter, init_unit_test_func, unit_test_main. - Boost.Test code in trunk is used as "the truth" for understanding how something actually works -- "The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline> The Computer Graphics Museum <http://computergraphicsmuseum.org> The Terminals Wiki <http://terminals.classiccmp.org> Legalize Adulthood! (my blog) <http://legalizeadulthood.wordpress.com>
Richard <legalize+jeeves <at> mail.xmission.com> writes:
[Please do not mail me a copy of your followup]
boost <at> lists.boost.org spake the secret code <loom.20130807T214918-704 <at> post.gmane.org> thusly:
boost <at> lists.boost.org spake the secret code <loom.20130802T232929-478 <at> post.gmane.org> thusly:
I lost my work on new docs unfortunately to broken laptop, still
trying to
revive it, but I'm lacking time to really get to it.
I wouldn't bother reviving your work on new docs since I am completely rewriting them and am almost finished.
Do you follow trunk or release state of Boost.Test?
I've been working based on trunk, but could easily adapt to another branch if that is the preferred place.
Trunk is the correct place for latest state of Boost.Test.
I posted a call for reviewers on May 1 and am on snapshot 6 right now.
Can I see it somewhere?
- Everything is written in Quickbook - It is a true rewrite, not an edit of existing docs
So you do not see aplace for any of an existing pages in your new documentation? What about examples and existing tutorials? Do you cover all the components of Boost.Test?
- Some Quickbook annotations are added to header files to briefly summarize the major classes/functions that a user of Boost.Test is likely to care about: test_unit, test_case, test_suite, master_test_suite_t, test_observer, unit_test_log_t, unit_test_log_formatter, init_unit_test_func, unit_test_main.
Why does this need to be part of source code?
- Boost.Test code in trunk is used as "the truth" for understanding how something actually works
So, you reverse engeneer all new features, right? Decorators, data based testing, New testing tools (what about old tools?), test unit filtering? Would you be interested in my input? We can take this offline. Gennadiy
[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <loom.20130808T054201-956@post.gmane.org> thusly:
- Everything is written in Quickbook - It is a true rewrite, not an edit of existing docs
So you do not see aplace for any of an existing pages in your new documentation? What about examples and existing tutorials? Do you cover all the components of Boost.Test?
I wrote all new tutorials, examples, user guide, etc. Over 4 years ago I posted this on boost-users when I wrote a series of tutorials on Boost.Test for my blog: "I don't know exactly what it is about the documentation, but its difficult for me to find stuff in there quickly. The easier it is to get started with a library, the more people use it. I don't know why, but Boost.Test feels hard to get started. Once I got it figured out, I decided that some tutorials would help others." This situation hadn't changed at all in 4 years, so I just decided to fix it by writing new documentation.
- Some Quickbook annotations are added to header files to briefly summarize the major classes/functions that a user of Boost.Test is likely to care about: test_unit, test_case, test_suite, master_test_suite_t, test_observer, unit_test_log_t, unit_test_log_formatter, init_unit_test_func, unit_test_main.
Why does this need to be part of source code?
This is how quickbook keeps documentation and header files synchronized.
- Boost.Test code in trunk is used as "the truth" for understanding how something actually works
So, you reverse engeneer all new features, right?
It's not clear what is a new feature and what is simply an undocumented internal mechanism. So no, I documented the stuff that everyone needs and the stuff that people appear to be using in boost by grepping trunk. This is already a little bit more than what the old documentation covered.
Would you be interested in my input? We can take this offline.
I will post for wider review once I finish my first pass, which is probably going to happen soon. Right now, I'm just using a few people for feedback as I go. -- "The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline> The Computer Graphics Museum <http://computergraphicsmuseum.org> The Terminals Wiki <http://terminals.classiccmp.org> Legalize Adulthood! (my blog) <http://legalizeadulthood.wordpress.com>
Richard <legalize+jeeves <at> mail.xmission.com> writes:
This situation hadn't changed at all in 4 years, so I just decided to fix it by writing new documentation.
Trunk version of docs did improve on that in my opinion, but this is besides the point.
- Some Quickbook annotations are added to header files to briefly Why does this need to be part of source code?
This is how quickbook keeps documentation and header files synchronized.
So quickbook is like doxigen? Does it parse C++ sources?
- Boost.Test code in trunk is used as "the truth" for understanding how something actually works
So, you reverse engeneer all new features, right?
It's not clear what is a new feature and what is simply an undocumented internal mechanism. So no, I documented the stuff that everyone needs and the stuff that people appear to be using in boost by grepping trunk. This is already a little bit more than what the old documentation covered.
What is that you cover that existing pages do not, for example? Did you base your decision on what is needed on content of Boost own unit tests? The problem with this is that these obviosly does not include any of new features and these are indeed completely missing from docs. Even worse they use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all these tools are now deprecated and I wouldn't spend any time detailing their use. New testing tools is the one to use from now on and these are the one that needs to be coverred.
Would you be interested in my input? We can take this offline.
I will post for wider review once I finish my first pass, which is probably going to happen soon. Right now, I'm just using a few people for feedback as I go.
You are free to do what you think best, but I would imagine that if you want something which reflects real state of Boost.Test (in other words something, which we can actually use for release), we probably need to talk sooner rather than later. Regards, Gennadiy
[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <loom.20130809T205009-764@post.gmane.org> thusly:
The problem with this is that these obviosly does not include any of new features and these are indeed completely missing from docs. Even worse they use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all these tools are now deprecated and I wouldn't spend any time detailing their use.
So you're going to break all the tests that have been written so far? I don't understand why this is desirable. -- "The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline> The Computer Graphics Museum <http://computergraphicsmuseum.org> The Terminals Wiki <http://terminals.classiccmp.org> Legalize Adulthood! (my blog) <http://legalizeadulthood.wordpress.com>
Richard <legalize+jeeves <at> mail.xmission.com> writes:
[Please do not mail me a copy of your followup]
boost <at> lists.boost.org spake the secret code <loom.20130809T205009-764 <at> post.gmane.org> thusly:
The problem with this is that these obviosly does not include any of new features and these are indeed completely missing from docs. Even worse they use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all these tools are now deprecated and I wouldn't spend any time detailing their use.
So you're going to break all the tests that have been written so far?
I don't understand why this is desirable.
We are not going to break anything. These tools are still there, but they are deprecated in favour of new interface. New documentation should cover new interface and can probably refer to last release for old tools. Gennadiy
On 08/09/2013 09:01 PM, Gennadiy Rozental wrote:
features and these are indeed completely missing from docs. Even worse they use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all these
BOOST_CHECK_EQUAL has been deprecated? What should be used instead?
features and these are indeed completely missing from docs. Even worse they use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all these
BOOST_CHECK_EQUAL has been deprecated? What should be used instead?
Very good question, when did this happen, where are the docs for the new version? Thanks, John.
John Maddock <john <at> johnmaddock.co.uk> writes:
BOOST_CHECK_EQUAL has been deprecated? What should be used instead?
Very good question, when did this happen,
It's not really "happened" yet. This is trunk state, it was not released yet.
where are the docs for the new version?
And that is the gist of this discussion ;). Gennadiy
Bjorn Reese <breese <at> mail1.stofanet.dk> writes:
On 08/09/2013 09:01 PM, Gennadiy Rozental wrote:
features and these are indeed completely missing from docs. Even worse
use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all
they these
BOOST_CHECK_EQUAL has been deprecated? What should be used instead?
BOOST_TEST( a == b ) This will produce as good an output. You can also do BOOST_TEST( a > b ) BOOST_TEST( a != b ) BOOST_TEST( a + b < 2 ) All these will produce detailed output including values of a and b in case if assertion fails. a and b could be collections, in which case above will do per element comparison. a and b could be floating point numbers in which case above will perform comparison with predefined tolerate (predefined for the series of assertions of for the whole test case, and we will also have an ability to specify it as second argument in above assertion). All of this and much much more is the function of new "super testing tool" BOOST_TEST. There are few rare examples where above will not work, BOOST_CHECK will be used instead. You can see more examples in Boost.Test unit tests. Gennadiy
On 08/10/2013 07:11 PM, Gennadiy Rozental wrote:
All these will produce detailed output including values of a and b in case if assertion fails. a and b could be collections, in which case above will do per element comparison. a and b could be floating point numbers in which case above will perform comparison with predefined tolerate (predefined for the series of assertions of for the whole test case, and we will also have an ability to specify it as second argument in above assertion). All of this and much much more is the function of new "super testing tool" BOOST_TEST.
Sounds good. Assuming that my foo() function fails, how difficult is it going to be to single-step into it (without setting breakpoints inside foo) from a BOOST_TEST(foo()) line? This is a very common scenario for me.
Bjorn Reese <breese <at> mail1.stofanet.dk> writes:
On 08/10/2013 07:11 PM, Gennadiy
Rozental wrote:
Assuming that my foo() function fails,
how difficult is it going to be
to single-step into it (without setting breakpoints inside foo) from a BOOST_TEST(foo()) line? This is a very common scenario for me.
New boost.test has support for this through two macros: BOOST_TEST_UNDER_DEBUGGER If you define this test module will compile in debugger friendly mode. BOOST_TEST_DEBUGABLE If you define this macro test module will perform assertions as usual if you run the test regularly and it will run in debugger friendly mode of you run under debugger (this only available on platforms where we can detect presence of debugger). The price you pay its extra compile time. Gennadiy
On 08/11/2013 03:52 AM, Gennadiy Rozental wrote:
If you define this macro test module will perform assertions as usual if you run the test regularly and it will run in debugger friendly mode of you run under debugger (this only available on platforms where we can detect presence of debugger). The price you pay its extra compile time.
Excellent. Thanks.
[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <loom.20130810T190308-14@post.gmane.org> thusly:
Bjorn Reese <breese <at> mail1.stofanet.dk> writes:
On 08/09/2013 09:01 PM, Gennadiy Rozental wrote:
features and these are indeed completely missing from docs. Even worse
use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all
they these
BOOST_CHECK_EQUAL has been deprecated? What should be used instead?
BOOST_TEST( a == b )
This will produce as good an output. You can also do
BOOST_TEST( a > b ) BOOST_TEST( a != b ) BOOST_TEST( a + b < 2 )
So what "level" is this? - warning (emit message, test case continues and is not marked failed) - check (emit message, test case contines and is marked failed) - require (emit message, test case does not contiue and is marked failed) -- "The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline> The Computer Graphics Museum <http://computergraphicsmuseum.org> The Terminals Wiki <http://terminals.classiccmp.org> Legalize Adulthood! (my blog) <http://legalizeadulthood.wordpress.com>
Richard <legalize+jeeves <at> mail.xmission.com> writes:
BOOST_TEST( a > b ) BOOST_TEST( a != b ) BOOST_TEST( a + b < 2 )
So what "level" is this?
This is check level, we'll also have BOOST_TEST_WARN, BOOST_TEST_CHECK(same as BOOST_TEST) and BOOST_TEST_REQUIRE. So, what the resolution? Are you interested to cover latest state of Boost.Test or do I need to push forward by myself? Do not take this wrong way - I would definitely prefer to work with someone who is more comfortable with writing docs than doing it all by myself. And I can even live with quickbook, if it can handle all we need. Yet I need to cover new Boost.Test, not rewrite docs for old one. I really hope we can collaborate on this. Regards, Gennadiy
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Gennadiy Rozental Sent: Tuesday, August 13, 2013 4:17 AM To: boost@lists.boost.org Subject: Re: [boost] [test] still broken in release
Richard <legalize+jeeves <at> mail.xmission.com> writes:
BOOST_TEST( a > b ) BOOST_TEST( a != b ) BOOST_TEST( a + b < 2 )
So what "level" is this?
This is check level, we'll also have BOOST_TEST_WARN, BOOST_TEST_CHECK(same as BOOST_TEST) and BOOST_TEST_REQUIRE.
So, what the resolution? Are you interested to cover latest state of Boost.Test or do I need to
push
forward by myself? Do not take this wrong way - I would definitely prefer to work with someone who is more comfortable with writing docs than doing it all by myself. And I can even live with quickbook, if it can handle all we need. Yet I need to cover new Boost.Test, not rewrite docs for old one. I really hope we can collaborate on this.
I hope so too. I find Richard's Quickbook/Doxygen version *much* more user-friendly. Putting the function and macro descriptors in the code is popular because it keeps the docs close to the code and makes it more likely that the two are kept in sync. Doxygen simply automates the process of making it accessible from the Quickbook C++ reference section. Of course the quality of the Doxygen comment descriptions is the key to making the docs really work for the user. (Too many people have been put off Doxygen because authors have thought that all they needed to do was to feed the C++ code into Doxygen and the job was done. This is quite wrong - the real task is still to add comments to document the functions and macros etc). I hope too that we can get the new Boost.Test fully accepted and working for all Boost libraries. But I understand how difficult it is to make changes when every other library depends on Boost.Test (or should do). Would it help to create a 'Son of Boost.Test' so that each library author can try out the new version without fear (and switch back if it doesn't work for them). Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
I hope so too. I find Richard's Quickbook/Doxygen version *much* more user- friendly.
Is this the same as the doxygen_xml2qbk tool in Boost.Geometry?
Doxygen simply automates the process of making it accessible from the Quickbook C++ reference section.
I've been pleased with Boost.Geometry's doxygen_xml2qbk, though it is brittle and I had to patch it to get it to generate the right results as previously it didn't list structure member variables or their documentation. See https://ci.nedprod.com/view/All/job/Boost.AFIO%20Build%20Documentation/Boost .AFIO_Documentation/doc/html/afio/reference.html. Niall --- Opinions expressed here are my own and do not necessarily represent those of BlackBerry Inc.
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Niall Douglas Sent: Wednesday, August 14, 2013 8:23 PM To: boost@lists.boost.org Subject: Re: [boost] [test] still broken in release
I hope so too. I find Richard's Quickbook/Doxygen version *much* more user- friendly.
Is this the same as the doxygen_xml2qbk tool in Boost.Geometry?
No - it is the original Doug Gregor et al "C++ reference section" system, as used by several Boost libraries docs. As I've said before, the vital detail is the quality of Doxygen comments in the code. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
Paul A. Bristow <pbristow <at> hetp.u-net.com> writes:
I hope so too. I find Richard's Quickbook/Doxygen version *much* more user-friendly.
I do not follow this statement. Why Boost.Test users would care what media is used for writing docs. How using doxygen make it more user-friendly than any other solution?
Putting the function and macro descriptors in the code is popular because it keeps the docs close to the code and makes it more likely that the two are kept in sync.
Doxygen simply automates the process of making it accessible from the Quickbook C++ reference section.
Of course the quality of the Doxygen comment descriptions is the key to making the docs really work for the user.
(Too many people have been put off Doxygen because authors have thought that all they needed to do was to feed the C++ code into Doxygen and the job was done. This is quite wrong - the real task is still to add comments to document the functions and macros etc).
I had an extensive expirience with Doxygen recently (had to document massive project at work). It does indeed have it's uses, but: 1. It is primarily should be used for *reference* documentation. It is not a good media for user guide kind of pages. It is fine to have few lines next to the function/class declaration, but once we start writing long complicated usage explanations code bacome unacceptantly cluttered for developers and unreadable for viewers. Take BOOST_TEST for example. It is just line in a header and probably 20 pages in docs. 2. It does help sometimes to see these comments next to headers, but they also bring false sense of security All too frequently I see incorrect doxygen statements next to modified code. Unfortunately compiler does not validate correctnesss of doc statements during compilation, so it requires strict discipline from developer to maintain these in correct state. Having docs in standalone form is not much better, but at least this have a distict indication that something else needs to be changed once code is modified. In any case this is minot point. 3. Doxygen is not smart enough. I spent lot of time telling it what to ignore. There are number of bugs and shortcomings in what it supports in modern C++. We can probably work around these. Overall I am fine with using doxygen comments in code, if it is not the only form of documentation and they are only responcible for reference docs. User guide with all the examples, build rules, detailed semantic explanations does not belong to the code. One other thing I hope we can keep is dynamic features of current user guide (like hidable example outputs)
Would it help to create a 'Son of Boost.Test' so that each library author can try out the new version without fear (and switch back if it doesn't work for them).
Not sure about the name ;)... Otherwise all library authors are free to use trunk version of Boost.Test to try new features. Regards, Gennadiy
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Gennadiy Rozental Sent: Wednesday, August 14, 2013 10:23 PM To: boost@lists.boost.org Subject: Re: [boost] [test] still broken in release
Paul A. Bristow <pbristow <at> hetp.u-net.com> writes:
I hope so too. I find Richard's Quickbook/Doxygen version *much* more user-friendly.
I do not follow this statement. Why Boost.Test users would care what media is used for writing docs. How using doxygen make it more user-friendly than any other solution?
Because it is familiar - the look'n'feel is similar to lots of other Boost libraries. They know how to navigate it.
Putting the function and macro descriptors in the code is popular because it keeps the docs close to the code and makes it more likely that the two are kept in sync.
Doxygen simply automates the process of making it accessible from the Quickbook C++ reference section.
Of course the quality of the Doxygen comment descriptions is the key to making the docs really work for the user.
(Too many people have been put off Doxygen because authors have thought that all they needed to do was to feed the C++ code into Doxygen and the job was done. This is quite wrong - the real task is still to add comments to document the functions and macros etc).
I had an extensive expirience with Doxygen recently (had to document massive project at work). It does indeed have it's uses, but:
1. It is primarily should be used for *reference* documentation. It is not a good media for user guide kind of pages.
Absolutely - it's only used for that. The link between Doxygen was done by Doug Gregor years ago and is used on many big Boost projects. Quickbook also provides a nice way of providing the main descriptive stuff, tutorials ... And Quickbook's code snippets ensure that the code in docs has actually compiled and run.
It is fine to have few lines next to the function/class declaration, but once we start writing long complicated usage explanations code become unacceptantly cluttered for developers and unreadable for viewers. Take BOOST_TEST for example. It is just line in a header and probably 20 pages in docs.
Yes - but you can easily provide links to the descriptive text sections and anchors too.
2. It does help sometimes to see these comments next to headers, but they also bring false sense of security
Yes - it would be better if the compiler was more tightly coupled to the documentation tool.
3. Doxygen is not smart enough.
OK, but Doxygen is the best tool that we have, and is still being improved. It's main weakness is controlling things that we don't want documented, but that could be improved with the will, and enthusiasm.
Otherwise all library authors are free to use trunk version of Boost.Test to try new features.
But that's a bit scary ;-) Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
On 08/15/2013 11:02 AM, Paul A. Bristow wrote:
OK, but Doxygen is the best tool that we have, and is still being improved.
FYI, the latest version of Doxygen can use libclang: http://lists.cs.uiuc.edu/pipermail/cfe-dev/2013-May/029747.html
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Bjorn Reese Sent: Thursday, August 15, 2013 11:53 AM To: boost@lists.boost.org Subject: Re: [boost] [test] still broken in release
On 08/15/2013 11:02 AM, Paul A. Bristow wrote:
OK, but Doxygen is the best tool that we have, and is still being improved.
FYI, the latest version of Doxygen can use libclang:
http://lists.cs.uiuc.edu/pipermail/cfe-dev/2013-May/029747.html
That's really good news (because Doxygen is currently confused by C++ code that won't even compile ;-) But also because it should give more control over what is passed to Quickbook. The major current downside of Doxygen is getting absolutely everything in the C++ reference section. This can make a C++ reference section very cluttered (though an index can help the user find what he is looking for). I'm sure we can improve this given the will and some expert input. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <loom.20130809T205009-764@post.gmane.org> thusly:
The problem with this is that these obviosly does not include any of new features and these are indeed completely missing from docs. Even worse they use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all these tools are now deprecated and I wouldn't spend any time detailing their use. New testing tools is the one to use from now on and these are the one that needs to be coverred.
I don't see you how can refer to these as 'deprecated' when they are what ships in boost 1.55 and BOOST_TEST does not ship with 1.55. -- "The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline> The Computer Graphics Museum <http://computergraphicsmuseum.org> The Terminals Wiki <http://terminals.classiccmp.org> Legalize Adulthood! (my blog) <http://legalizeadulthood.wordpress.com>
participants (7)
-
Bjorn Reese -
Gennadiy Rozental -
John Maddock -
legalize+jeeves＠mail.xmission.com -
Niall Douglas -
Paul A. Bristow -
Tim Blechmann