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: Krzysztof Jusiak (krzysztof_at_[hidden])
Date: 2016-02-26 09:12:53

On Fri, Feb 26, 2016 at 1:56 PM, Krzysztof Jusiak <krzysztof_at_[hidden]>
wrote:

> On Fri, Feb 26, 2016 at 12:55 PM, Paul A. Bristow <pbristow_at_[hidden]
> > wrote:
>
>>
>>
>> > -----Original Message-----
>> > From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of
>> Krzysztof Jusiak
>> > Sent: 23 February 2016 12:41
>> > To: boost_at_[hidden]
>> > 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
>
>
Moreover,
https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/master/CppCoreGuidelines.md
is
using markdown too.
I think that means something.

>
>> 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.
>
>
>>
>> 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.
>
>
>> So nice try, but no banana.
>>
>> Paul
>>
>> PS The one thing that we could do is to use the CSS to make it easy for
>> users to impose their own syntax color scheme onto Boost
>> libraries.  I'm really sensitive to this (and for chromatically
>> challenged it will be a major readability issue).
>>
>> I feel person CSS should be a quick win.
>>
>> ---
>> Paul A. Bristow
>> Prizet Farmhouse
>> Kendal UK LA8 8AB
>> [phone]
>>
>>
>>
>>
>>
>>
>>
>>
>>
>> _______________________________________________
>> Unsubscribe & other changes:
>> http://lists.boost.org/mailman/listinfo.cgi/boost
>>
>
>