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 Fultz II (pfultz2_at_[hidden])
Date: 2016-02-26 10:04:25

On Friday, February 26, 2016 at 6:56:00 AM UTC-6, Paul A. Bristow wrote:
>
>
>
> > -----Original Message----- 
> > From: Boost [mailto:boost-..._at_[hidden] <javascript:>] On Behalf 
> Of Krzysztof Jusiak 
> > Sent: 23 February 2016 12:41 
> > To: bo..._at_[hidden] <javascript:> 
> > Subject: [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! 
> > 
> > Dear Boosters, 
> > 
> > I have just released version 1.0.0 of experimental Boost.DI library. 
> > Your C++14 header only Dependency Injection library with no 
> dependencies. 
> > 
> > Library entered Boost Formal Review Queue some time ago and right now, 
> > IMHO, is ready to be reviewed. 
> > http://www.boost.org/community/review_schedule.html 
> > 
> > Therefore, I'm looking for a Review Manager, so if you think that 
> Boost.DI 
> > is good enough to be reviewed and you would like to help with it, please 
> > let me know. Thank you! 
> > 
> > In the mean time check out the library yourself online! 
> > http://boost-experimental.github.io/di/examples/index.html 
> > 
> > Or read the interactive documentation... 
> > http://boost-experimental.github.io/di 
> > 
> > Or check out the source code... 
> > https://github.com/boost-experimental/di 
> > 
> > Why Boost.DI? 
> > * Boost.DI has none or minimal run-time overhead 
> > * Boost.DI compiles fast / Faster than Java-Dagger2! 
> > * Boost.DI gives short diagnostic messages 
> > * Boost.DI is non-intrusive 
> > * Boost.DI reduces boilerplate code 
> > * Boost.DI reduces testing effort 
> > * Boost.DI gives better control of what and how is created 
> > * Boost.DI gives better understanding about objects hierarchy 
> > 
> > Read more why here -> http://boost-experimental.github.io/di/index.html 
> > 
> > Any feedback is more than welcome! 
>
> This documentation looks very swish and sexy and has obviously received a 
> lot of thoughtful work. 
>
> I'm not needing injections at present (apart from monkey glands perhaps 
> ;-)  but you told a plausible story with good graphics 
> (though I was left with a bit of a Huh? feeling). 
>
> I'm not at all convinced that it's really worth making it all interactive. 
>   
>
> Without going all NIH (Not Invented Here), I feel there are some big 
> things missing. 
>
> 1  Versioning - each released Boost version needs its own version of the 
> docs - or people will get really confused. 
>

For Fit, readthedocs.org takes care of that for me and generates 
documentation
for each versions(as well as the latest off of master). If I was using
quickbooks I wouldn't be able take advantage of third-party tools like this.
 

>
> 2  Not standalone - we aren't all always online.  HTML version is vital, 
> single PDF is neatest. 
>

>From HTML, it can be integrated into Dash/Zeal which is the neatest.
 

>
> 3  Unfamiliar.  For a 'simple' (in what it offers, rather than its 
> internal complexity) library like this, this is not so important, 
> but the toolchain doesn't scale IMO. 
>
> 4  Difficult to find what you are looking for.  This start with the 
> library name Boost.DI - how are you going to know that you might 
> want it in the first place?  (There are lots of other 'pet' library names 
> that will not draw users unless they know what they are 
> looking for).  And it gets worse when you fail to find a detailed table of 
> contents and class, macro, function, concept and general 
> index.  
>

> For me 'how to find' is an major documentation problem that we haven't 
> cracked yet. 
>
> 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. 
>
> 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. 
>
 

With mkdocs, the users can make changes with plain text. Plus, its written 
in
markdown(which almost every developer on github or stackoverflow knows) 
unlike
Quickbooks mark-up which is only known by core boost developers.
 

>
> 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.   
>

Same with mkdocs.
 

>
> Anyone can change the indexing by changing the source code (or the 
> index.idx plain text-file that controls Boost auto-indexing). 
>

Another not so well known configuration.
 

>
> 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. 
>

And thats one major advantage of mkdocs, its easy for the user to generate 
the
docs on their own as well as integrate easily with third-party tools. This 
is
important, especially, if the user is contributing a feature that requires
sizable documentation(they will definitely want to preview the docs).

Having easier tools makes will help improve community contribution.

Paul F.