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.