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 2/26/2016 10:20 AM, Krzysztof Jusiak wrote:

On Fri, Feb 26, 2016 at 2:48 PM, Paul A. Bristow wrote:

...

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Krzysztof Jusiak Sent: 26 February 2016 13:57 To: boost@lists.boost.org 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!

...

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.

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.

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.

...

...

...

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.

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.

Many libraries? I see geometry, numeric and gil, its not a lot out of ~120 libraries.

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.

...

...

...

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.

I doubt it.

You've just reinvented a fancy wheel!

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.