|
|
Boost : |
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: Krzysztof Jusiak (krzysztof_at_[hidden])
Date: 2016-02-27 12:51:16
On Sat, Feb 27, 2016 at 10:28 AM, Paul A. Bristow <pbristow_at_[hidden]>
wrote:
>
> 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).
>
>
I couldn't agree more with you comment.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk