[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! Cheers, Kris
AMDG A few documentation nits: * The examples often overflow the window and there is no horizontal scroll bar. * What does CPP(SPLIT) mean? CPP, CPP(BTN), and CPP(SHOW) too. * I find the tables without any borders hard to read. * "But what about values? renderer requires device, which, by default, was zero initialized." Are you sure that you don't mean /value/-initialized? (Yes, I know they're equivalent in this case.) * When I follow the link to constructible in "If you want change the default behaviour and be sure that all required dependencies are bound and not zero initialized take a look at constructible policy." which goes here: http://boost-experimental.github.io/di/user_guide/index.html#di_constructibl..., it doesn't give any clue about how I'm supposed to use constructible. In Christ, Steven Watanabe
On Tue, Feb 23, 2016 at 3:43 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
AMDG
Thanks for you feedback.
Can you tell me which browser are you using, please? I tested it on newest versions of Chrome/Firefox and IE and looks fine.
* What does CPP(SPLIT) mean? CPP, CPP(BTN), and CPP(SHOW) too.
CPP uses Java Script to show the code, highlight it and let it test online. However, you have to have Java Script enabled in order to see the documentation properly.
* I find the tables without any borders hard to read.
There are borders on the tables. I really would like to know your configuration, please?
Fair point, thanks for that. I have updated the doc accordingly.
I think it's because you can't see examples and code due to lack of Java Script as most information is described using it.
AMDG On 02/23/2016 10:43 AM, Krzysztof Jusiak wrote:
Firefox w/ javascript disabled.
* What does CPP(SPLIT) mean? CPP, CPP(BTN), and CPP(SHOW) too.
CPP uses Java Script to show the code, highlight it and let it test online.
I can understand needing javascript to test the code online and I can sort of justify using it for higlighting (though I'm not really happy about that), but it makes no sense at all for the code to require javascript to display at all.
It's because you're using javascript to do something that ought to be handled by css. In Christ, Steven Watanabe
On Tue, Feb 23, 2016 at 10:23 PM, Andrey Semashev <andrey.semashev@gmail.com
wrote:
I created a ticket do display the code without JS -> https://github.com/boost-experimental/di/issues/208. However, highlighting will require JS to be enabled. I get your point that it might be done statically, however, mkdocs is using JS for it and I don't see a huge reason to change it. Anyway, on this note, I really do not understand why requirement of Java Script is such a big thing? Data shows that only 1-2% of people don't have it enabled either way, so it's a really small number of people affected. Almost all pages are using Java Script in some way either way, so why Boost can't take advantage of it as others languages do? IMHO, maybe a bit controversial, not being more aggressive with the web tools available is one of the reasons why C++ is still considered old fashioned and so hard to work with. These days we can do so much better, Modern C++ allow us to code in a more productive way than even before, but it's hard to show all these benefits for new/old users with a boring/old fashion documentation. Therefore, Boost.DI doc is so interactive... * You can comment on the page * You have a chat to discuss issues * Finally you can run the code in your browser! IMHO this type of documentation is more appealing to the average users as they can easily see how the library works and how good modern C++ becomes. What I mean by that, is that they can easily spot that the library... * Compiles quickly -> you can change it online and see! * Error messages are short and nice -> again, You can tryi 5 sec and seen the result! * Can be integrated easily -> it's done on the web, how hard it can be? (Boost.DI therefore is just one header and no dependencies) * Has support via comments/chats -> You don't have to subscribe to lists etc... I think Boost and C++ can win a lot by showing how good Modern C++ is, especially right now, when languages like Rust/Nim/Go/D are already showing how easily they are in comparison to OLD C++! It will come with a bit of cost, like enabling JS, but I think it's the cost worth taking! BTW. I would really appreciate comments about the library too. Cheers, Kris
On Wed, Feb 24, 2016 at 3:39 PM, Krzysztof Jusiak <krzysztof@jusiak.net> wrote:
Well, to me the JS-only markup would be a reason enough...
Anyway, on this note, I really do not understand why requirement of Java Script is such a big thing?
There are two aspects to this. First is conceptual. Using JS where static content can and should be used is just wasteful in terms of client performance and battery life. I'm sad to see that JS is often viewed as a hammer for every nail and we can see JS projects that should have never existed in the first place. I hate to see web pages that load CPU, are difficult to scroll and cause closing the tab take seconds. Second is practical. Boost docs are also built into pdf, and JS cannot be used there. Also there are people who disable JS in web browsers. Whether these people are 1% or not I cannot tell, but I don't think you want to deny them reading your docs. Then there's some people who'd like to have the docs offline. This is certainly the case for Boost packagers. Don't misunderstand me, I don't mind using JS for interactive stuff you mentioned - when the docs are online. But all these bells and whistles should be strictly optional and the docs should be viewable without them. You could say the code snippets are viewable without highlighting and that is true, but I can't say such docs are comfortable to read. And since static highlighting is easy with Doxygen or QuickBook, I think it should be done.
On Wed, Feb 24, 2016 at 1:19 PM, Andrey Semashev <andrey.semashev@gmail.com> wrote:
I agree that there should be an option to see it without JS, however, I don't think it's a priority these days. As I mentioned before I'm going to fix visibility of code when JS is disabled ( https://github.com/boost-experimental/di/issues/208). I don't see much problem in generating pdf from markdown and JS either. I would even say it might be done with one-liner ;) Furthermore, If it comes to JS you can change the style/theme online. Imagine someone doesn't like the highlighting provided and would like a different one. With the static solution, another version of the website would have to be provided. JS + CSS let you change it dynamically. IMHO it's a great timing for all C++ developers to appreciate JS/HTML5 as we have tools like Emscripten/Cheerp to our disposition now. I predict that more and more stuff will be written or ported this way as you can write one code for all platforms including Web and Mobile.
AMDG On 02/24/2016 07:07 AM, Krzysztof Jusiak wrote:
I have a hard time imagining anyone bothering to fiddle with the highlighting settings like this. In any case, if your static html includes a fixed color scheme, you're doing it wrong. The actual colors should be set in CSS regardless of whether you're using JS or not. In Christ, Steven Watanabe
On Thu, Feb 25, 2016 at 12:06 AM, Steven Watanabe <watanabesj@gmail.com> wrote:
Yea, most of the stuff will be handled by CSS, however, you have to add tags for the keywords in the code. Either way it's not giving you a possibility to change it, so it doesn't really from the user perspective, I guess. Anyway, I have prepared a Boost-like version of the documentation (based on Paul's boost theme) which does not require JS, so please check it out. http://boost-experimental.github.io/di/boost/ It still require some tweaks, but it's usable already.
On Thu, Feb 25, 2016 at 5:20 PM, Edward Diener <eldiener@tropicsoft.com> wrote:
However, your point is absolutely valid as it's not visible in the doc. Thanks! Fixed with this commit, should be updated in a few minutes.. https://github.com/boost-experimental/di/commit/30702a9898de74acc00f69d4abdc...
On Wednesday, February 24, 2016 at 6:39:52 AM UTC-6, Krzysztof Jusiak wrote:
Mkdocs can use pygments to highlight code blocks statically. However, I've found that highlight.js does a much better job at highlighting. It seems pygments would get confused by C++ syntax easily.
But how does the documentation deal with versioning? When you go back to a previous version how does all the interaction work then? Also, how does it work with offline documentation browsing such as Dash/Zeal?
On Wednesday, February 24, 2016 at 6:39:52 AM UTC-6, Krzysztof Jusiak wrote:
On Tue, Feb 23, 2016 at 10:23 PM, Andrey Semashev <andrey....@
> <javascript:>
Thanks. It's a really valid point. Well, chats and comments do not refer to any version so, I guess, they are okay. Code to be ran is taken from github and is using a specific version, so it's not an issue too. Actually, everything is prepared to add a button next to compile button with all versions available where user can change the version and verify the behavior. I haven't added it yet, because I have really one version of the library so far. Other option is to maintain different versions of the documentation for different releases as Boost is doing either way. The only thing which would be different is the fact that code examples will point to a specific release. If it comes to offline browsing, I'm not sure actually. I will check it out tho. Either way for offline browsing either via pdf or dash/zeal a static version would have to be generated, which is not a big deal and I can provide that.
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost -- View this message in context: http://boost.2283326.n4.nabble.com/Experimental-Boost-DI-v1-0-0-released-Loo... Sent from the Boost - Dev mailing list archive at Nabble.com.
On 25/02/2016 06:50, Kris wrote:
Boost does already maintain separate snapshots of the documentation for different releases of Boost. Which I think was part of Krzysztof's point -- what happens when someone browsing the v1.59 docs adds a comment that something is wrong in the doc, while people looking at the v1.61 docs see something completely different (possibly already fixed) and then get confused?
On Fri, Feb 26, 2016 at 4:36 AM, Gavin Lambert <gavinl@compacsort.com> wrote:
Yea, exactly. It's a really valid question about comments tho. I was wondering myself about that and disqus (by default) generates comments per URL, which means that Boost separate snapshots would solve that as well because v_1.59 will have separate comments to version v_1.60, which, I guess, it's what we really want. Chat, on the other hand, would the same throughout all versions as its flow, usually, looks like that: - User: What about feature A? - Dev: Implemented in v1.62 ...
On Tue, Feb 23, 2016 at 7:19 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
Fair do's. I created a ticket to support code displaying without js enabled. You can check it found here -> https://github.com/boost-experimental/di/issues/208
It's actually done via CSS. Documentation using markdown and mkdocs to display with slightly modified readthedocs theme.
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. 2 Not standalone - we aren't all always online. HTML version is vital, single PDF is 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. 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. 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. 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 +44 (0) 1539 561830
On Fri, Feb 26, 2016 at 12:55 PM, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
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.
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.
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.
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...
The same apply to Markdown. Markdown is well known, really easy and very popular too.
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.
I would say with markdown whatever is possible with quickbook is also possible just in an easier way.
On Fri, Feb 26, 2016 at 1:56 PM, Krzysztof Jusiak <krzysztof@jusiak.net> wrote:
Moreover, https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/master/CppCoreGui... is using markdown too. I think that means something.
OK - Markdown is less powerful than Quickbook, but Quickbook isn't rocket science - if you had trouble getting started, you should have asked for help on the Boost lists. Once working, Quickbook really isn't difficult. It really comes into its own when dealing with 'bigger' libraries.
Don't see any reason why markdown might not be generated from Doxygen comments.
Indeed, I think this will happen, which is why having Doxygen-syntax comments in the source and header code is the really important thing.
Quickbook doesn't have support for Doxygen either way and any try caused a LOT of pain.
They work very well together, as you will see from many libraries using both.
I would say with markdown whatever is possible with Quickbook is also possible just in an easier way.
I doubt it. You've just reinvented a fancy wheel! Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On Fri, Feb 26, 2016 at 2:48 PM, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
I didn't have problems to start with quickbook. Well, maybe it was painful to set it up, but oh well. I haven't found it really powerful tho. A lot of things I wanted were really hard to achieve. Anyway, I have done quickbook version of the spec in the beginning -> https://github.com/boost-experimental/di/tree/d97ee097ff32123ff9242d39629595... I started like that, but I ended up having plenty of hard to maintain scripts fixing quickbook generated code. Moreover, it was really slow to develop as well. I decided to try doxygen afterwards (like hana does). It was a bit clumsy too. Markdown, on the other hand, suits my needs perfectly.
Many libraries? I see geometry, numeric and gil, its not a lot out of ~120 libraries. I also have seen Niall Douglas effort trying to generate doxygen for AFIO which was quite painful.
Well, its way easier to get support when using markdown as its used worldwide. Configuration is simpler too. You can even push your changed to readthedocs.org and you done. With quickbook you have to check out boost compile it, set up all docutils/xlst, etc.. and as boost quickbook is used just by boost support is limited to boost mailing list, but it's just my opinion.
You've missed the Boost.Math library which has nearly as much documentation as other libraries together.
I would say with markdown whatever is possible with Quickbook is also possible just in an easier way.
How does markdown handle code snippets? Code snippets seem like a 'must have' feature, but you just seem to be pasting code in. Experience shows that this is a recipe for mistakes. What You See is What Compiles and Runs (WYSWCR) is what we need. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On 2016-02-26 21:23, Paul A. Bristow wrote:
There's a rough list: $ for file in `find libs -name Jamfile.v2`; do grep -q "doxygen" "$file" && grep -q "quickbook" "$file" && echo "$file" ; done libs/core/doc/Jamfile.v2 libs/move/doc/Jamfile.v2 libs/test/doc/Jamfile.v2 libs/numeric/odeint/doc/Jamfile.v2 libs/chrono/doc/Jamfile.v2 libs/tti/doc/Jamfile.v2 libs/local_function/doc/Jamfile.v2 libs/scope_exit/doc/Jamfile.v2 libs/sync/doc/Jamfile.v2 libs/algorithm/doc/Jamfile.v2 libs/type_index/doc/Jamfile.v2 libs/heap/doc/Jamfile.v2 libs/dll/doc/Jamfile.v2 libs/property_tree/doc/Jamfile.v2 libs/lockfree/doc/Jamfile.v2 libs/sort/doc/Jamfile.v2 libs/random/doc/Jamfile.v2 libs/xpressive/doc/Jamfile.v2 libs/mpi/doc/Jamfile.v2 libs/log/doc/Jamfile.v2 libs/crc/doc/Jamfile.v2 libs/accumulators/doc/Jamfile.v2 libs/compute/doc/Jamfile.v2 libs/units/doc/Jamfile.v2 libs/ratio/doc/Jamfile.v2 libs/icl/doc/Jamfile.v2 libs/intrusive/doc/Jamfile.v2 libs/interprocess/doc/Jamfile.v2 libs/container/doc/Jamfile.v2 libs/utility/identity_type/doc/Jamfile.v2 libs/functional/overloaded_function/doc/Jamfile.v2
On Fri, Feb 26, 2016 at 8:45 PM, Andrey Semashev <andrey.semashev@gmail.com> wrote:
Fair point. I wasn't aware more libraries is using it. Still way more not using doxygen but that's not the point as having doxygen documentation has a lot benefits. The problem with generated quickbook doxygen the standard way is that it's not that useful because, AFAIK, its a reference with leasted headers and functions. http://www.boost.org/doc/libs/1_60_0/doc/html/property_tree/reference.html#h... Unless, I'm wrong?
No - you are absolutely correct that this isn't much help and is why Doxygen has a bad reputation with some. People have the totally misguided impression that just running Doxygen on the header files is a 'job done'. That's entirely wrong - they haven't even started the job! You have to document what the classes, functions, macros, templates and files actually do! describing their preconditions, post conditions, throws or not ... and for this there is a de facto standard that I call the Doxygen syntax. It provides categories like \pre \post \return \param \tparam \throw ... and a simple mark-up language, including code sections with syntax coloring etc. Soon, the Clang compiler will be able to process these comments for Doxygen (rather than using its own struggling-with-fancy-C++-templates parser) and emit the results in a useful way. When this is done, the C++ reference section immediately becomes invaluable because you can click on each item like a function or class and read what is does. Index(es) also takes you straight to the item. (And you can read the comments as you go if you are reduced to reading the header file itself). All this is hard work (and very tedious if done retrospectively) so few people have done it properly yet. For future-proofing, the vital information is stored in a standard-ish way, so it can be processed by other tools to give your preferred look'n'feel, SGI-ish if you like that (or not, if like me, you hate it). HTH Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On Friday, February 26, 2016 at 12:23:22 PM UTC-6, Paul A. Bristow wrote:
Well with the Fit library it uses two phases to build the documentation. So the first phase will either paste in the snippets from cpp files or it will extract snippets from markdown and put them in a cpp file. I use a similar technique to build by my presentations for C++Now or CppCon. I write my presentation in markdown with reveal.js, and then a separate tool pastes my code snippets into the markdown. Zach Laine is the one who wrote the tool for the presentations. I just took it from him. So markdown is very capable of What You See is What Compiles and Runs (WYSWCR). Paul
On 2/26/2016 10:20 AM, Krzysztof Jusiak wrote:
You haven't looked very hard, to say the least. Try again !
I also have seen Niall Douglas effort trying to generate doxygen for AFIO which was quite painful.
That is Niall Douglas's problem and not doxygen's problem. I am not claiming doxygen is perfect by a long shot but it is quite adequate for generating documentation from source code. I am also pretty sure that you know that doxygen has a very large user base in the programming world. But the issue is not doxygen and I would be the first to agree that a library developer should be able to use whatever he likes to generate the documentation for his library, just as long as he realizes that end-user's may want to view the docs both online and offline. What Boost almost certainly doesn't want is for the end-user to have major requirements just to view a library's documentation. If as the OP has done different levels of the same documentation is part of a library, depending on the end-user's preference, that's fine with me. But the basic level of doc needs to be accessible for the end-user with the least amount of outside requirements possible.
On Friday, February 26, 2016 at 7:57:14 AM UTC-6, Krzysztof Jusiak wrote:
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
On Friday, February 26, 2016 at 6:56:00 AM UTC-6, Paul A. Bristow wrote:
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.
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.
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.
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.
participants (9)
-
Andrey Semashev -
Dominique Devienne -
Edward Diener -
Gavin Lambert -
Kris -
Krzysztof Jusiak
-
Paul A. Bristow -
Paul Fultz II -
Steven Watanabe