-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Niall Douglas Sent: 13 January 2017 08:35 To: boost@lists.boost.org Subject: Re: [boost] Boost Cmake Modules
* Autodiscovers any tests you have and sets them up with ctest
This is interesting. But I don't think it scales. Some tests require linking in multiple sources, or require certain flags to be enabled. I really don't see how to autodiscover tests that will work for most boost libraries. Perhaps a `bcm_auto_test` function could be called by the author to do that(I would like to know what kind of conventions you follow when discovering the tests), and for libraries that have more complicated testing infastructure and add the tests manually with `bcm_add_test`.
The way it scales is that it makes use of directory structure. So if you fire .cpp files into /test, each is considered a ctest target, but if you put them into /test/somedir they get new semantics. In particular, you'll see Boost.AFIO v2 uses a /test structure which says to use Boost.KernelTest which is a new meta-test infrastructure.
* Provides out of the box CI ctest scripting which uploads results to a CDash for your project and updates your github website with the output from doxygen
This is probably useful for libraries that use doxygen. Using sphinx or mkdocs, I don't need to push changes out to github, as ReadTheDocs will update the documentation on push. Plus it will store the documentation for different tagged versions as well. This scales much nicer than using github pages.
I don't anybody who has ever used doxygen for anything serious has ever been happy with it. The good folks over at DoxyPress did an amazing job at refactoring doxygen, but in the end the fundamental design is just broke.
Problem is, and I think most would also agree here, there isn't anything better than doxygen for C++ reference docs. ReadTheDocs + Breathe generates what I find to be unusable reference docs. Formatting which suits Python well suits C++ terribly.
Many years ago Stefan (along with Dave Abrahams) championed a new C++ docs tool which was much better than doxygen, but in the end the effort required to finish it proved difficult to make happen. I'm sure most would agree what a shame.
If anybody knows of a tool which can understand doxygen markup but generates much better reference docs, I would be *extremely* interested. The really key part is that new C++ docs tooling *needs* to grok doxygen markup. So many new tools don't, and therefore get no traction because so many C++ codebases are locked into doxygen markup.
I agree that I don't find the C++ output from Doxygen itself attractive (though it is partly a look'n'feel prejudice). But I've saying for years that the really important 'standard' is the Doxygen-comment-syntax or markup. It's fairly simple (but takes a lot of variants to meet the prejudice of many different languages) but it's the only thing that is anywhere near to a standard. So you are definitely right that any tool *must* grok Doxygen comment syntax. And that all new code needs to add its comments to the code in this format. I'd like to see this as a Boost requirement - the comments are useful to those just reduced to reading the source code, up to those using tools that produce a fancier output and indexes. The tool that is best suited to the first pass of the C++ comments is the compiler itself, and that is what the Doxygen author Dimitri van Heesch (from 1997 to date) has been doing for a year or so with Clang. How do we focus new tool builders attention on starting from the right place? Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830