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:23:00

On Friday, February 26, 2016 at 7:57:14 AM UTC-6, Krzysztof Jusiak wrote:
>
> On Fri, Feb 26, 2016 at 12:55 PM, Paul A. Bristow <pbri..._at_[hidden] 
> <javascript:>> 
> 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. 
> > 
>
> Don't see any problem here. It's pretty much them same as any other spec. 
> 1. Code is versioned so there is no issue with 'Run this code' will refer 
> to a proper version 
> 2. Comments are versioned  as they depends on URL 
> 3. Chat is common for all versions 
>
>
> > 
> > 2  Not standalone - we aren't all always online.  HTML version is vital, 
> > single PDF is neatest. 
> > 
>
> I will provide pdf version, it's really easy to generate pdf from 
> markdown. 
> I will do it from http://boost-experimental.github.io/di/boost/ so it 
> will 
> have boost look and feel. 
>
>
> > 
> > 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. 
> > 
>
> Therefore, http://boost-experimental.github.io/di/boost/ theme which has 
> the same look and feel as any other Boost library 
> using quickbook. Generated from the same markdown, not fancy stuff, no 
> java 
> script, etc. 
>
>
> > 
> > 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. 
> > 
>
> I'm not sure whether I do understand your point. IMHO developers are not 
> browsing boost libraries trying to check whether 
> a library might be useful to them or not. It's rather the opposite way. 
> They have a problem and they are trying to check whether 
> there is a library solving it. DI is a design pattern and really popular 
> in 
> other languages and therefore it would be easy to find 
> by them. 
>
>
> > 
> > 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. 
>
>
> > 
> > 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. Quickbook doesn't have support for doxygen either 
> way and any try caused a LOT of pain. 
>

Actually for the Fit library, I have inline comments in the header file. I 
do
this by using a two phase doc generation. So, first I extract the
documentation from the header files, and then extract the example code into 
a
cpp file so the examples can be built and ran as well. Then I generate the
docs with mkdocs.

Paul