Re: [boost] Boost Cmake Modules

Subject: Re: [boost] Boost Cmake Modules
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2017-01-13 05:12:32

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Niall Douglas
> Sent: 13 January 2017 08:35
> To: boost_at_[hidden]
> 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
[phone]