Re: [boost] [Experimental Boost.DI] [v1.0.0 released] [Looking for a Review Manager] Your C+14 Dependency Injection library with no overhead and compile time creation guarantee!

Subject: Re: [boost] [Experimental Boost.DI] [v1.0.0 released] [Looking for a Review Manager] Your C+14 Dependency Injection library with no overhead and compile time creation guarantee!
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-02-27 05:28:58

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Krzysztof Jusiak
> Sent: 26 February 2016 22:02
> To: boost_at_[hidden]
> Subject: Re: [boost] [Experimental Boost.DI] [v1.0.0 released] [Looking for a Review Manager] Your C+14 Dependency
> Injection library with no overhead and compile time creation guarantee!
> 
> On Fri, Feb 26, 2016 at 8:45 PM, Andrey Semashev <andrey.semashev_at_[hidden]>
> wrote:
> 
> > On 2016-02-26 21:23, Paul A. Bristow wrote:
> >
> The problem with generated quickbook doxygen the standard way is that it's
> not that useful because, AFAIK,  its a reference with leasted headers and
> functions.
> http://www.boost.org/doc/libs/1_60_0/doc/html/property_tree/reference.html#header.boost.property_tree.exceptions_
> hpp

No - you are absolutely correct that this isn't much help and is why Doxygen has a bad reputation with some.

People have the totally misguided impression that just running Doxygen on the header files is a 'job done'.

That's entirely wrong - they haven't even started the job!

You have to document what the classes, functions, macros, templates and files actually do!

describing their preconditions, post conditions, throws or not ... and for this there is a de facto standard that I call the Doxygen
syntax.  It provides categories like \pre \post \return \param \tparam \throw ...   and a simple mark-up language, including code
sections with syntax coloring etc.

Soon, the Clang compiler will be able to process these comments for Doxygen (rather than using its own
struggling-with-fancy-C++-templates parser) and emit the results in a useful way.

When this is done, the C++ reference section immediately becomes invaluable because you can click on each item like a function or
class and read what is does.  Index(es) also takes you straight to the item.  (And you can read the comments as you go if you are
reduced to reading the header file itself).

All this is hard work (and very tedious if done retrospectively) so few people have done it properly yet.

For future-proofing, the vital information is stored in a standard-ish way, so it can be processed by other tools to give your
preferred look'n'feel, SGI-ish if you like that (or not, if like me, you hate it).

HTH 

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]