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!

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 javascript:> wrote:

...

...

-----Original Message----- From: Boost [mailto:boost-...@lists.boost.org javascript:] On

...

Krzysztof Jusiak

...

Sent: 23 February 2016 12:41 To: bo...@lists.boost.org 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,

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

...

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