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-26 09:48:04

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Krzysztof Jusiak
> Sent: 26 February 2016 13:57
> 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!

 > 4  Not maintainable.  This is a BIG issue.  We are already seeing a lot of
> > Boost libraries where the documentation cannot be
> > maintained by anyone other than the original author (they all disappear
> > eventually).  Some have been completely refactored (a lot of
> > rather tedious work) but in several cases we have effectively given up on
> > making any changes to the documentation.  This is really,
> > really BAD.
> >
> 
> I would disagree with this one. IMHO markdown is well known and way easier
> then quickbook. Generating doc is trivial, might be even
> done online. Generates doc in 0.1 s. QuickBook is so really, really heavy
> in comparison. It's way easier to change markdonw.
> https://raw.githubusercontent.com/boost-experimental/di/cpp14/doc/user_guide.md
> 
> 
> > Using the Quickbook mark-up language (for example because it is used for
> > many libraries) anyone can make small changes with any
> > plain text editor, and there are many people who can make much bigger
> > revisions.
> 
> The same apply to Markdown. Markdown is well known, really easy and very
> popular too.

OK - Markdown is less powerful than Quickbook, but Quickbook isn't rocket science - if you had trouble getting started, you should
have asked for help on the Boost lists.  Once working, Quickbook really isn't difficult.  It really comes into its own when dealing
with 'bigger' libraries.

> > Using Doxygen-syntax comments in the source code, anyone can easily change
> > these comments with their preferred IDE or editor.  All
> > changes will appear in documentation automatically.
 
> Don't see any reason why markdown might not be generated from Doxygen
> comments.

Indeed, I think this will happen, which is why having Doxygen-syntax comments in the source and header code is the really important
thing.

> Quickbook doesn't have support for Doxygen either
> way and any try caused a LOT of pain.

They work very well together, as you will see from many libraries using both.

> > Anyone can change the indexing by changing the source code (or the
> > index.idx plain text-file that controls Boost auto-indexing).
> >
> > Setting up the building tools is some hassle (like all other tools,
> > including getting endless Javascript updates!),
> > but these tools don't need to be used by the person who makes the
> > documentation changes - the build process will take care of that.

> I would say with markdown whatever is possible with Quickbook is also
> possible just in an easier way.

I doubt it.

You've just reinvented a fancy wheel!

Paul

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