On 5/26/17 11:57 PM, Vicente J. Botet Escriba via Boost wrote:
I believe what Robert mean is that the generated documentation of Boost.Outcome using doxygen has a lot of flaws. Of course it is tempting to say that it is because of doxygen.
As you showed in the examples we can do better. Using Doxygen requires to be more careful and sometimes replace some possible issues by workaroounds.
Nevertheless Doxygen on code using the pre-processor is a nightmare. Have you experience on these cases?
I will tale a deeper look at your examples :)
I understand the appeal of Doxygen. The idea if annotating the code with narrative comments which can accessed in a user friendly form is very appealing. It's natural for a programmer, easy to do, easier to keep up to date and is less tedious than building a giant reference after the fact. It also embodies the ideas and principles of literate programming in a practical way. So I see a lot of good in it. BUT a) It's support for templates is limited to specification of template parameters. It has no way to specify Type Requirements (aka concepts) aside from just typing in the narrative. It has no way to specify a concept and refer to it. b) It's doesn't seem a convenient method for specifing things like tutorials, examples, design concepts etc. c) By providing a place to add a little narative to each method it gives the programmer the impression that he's documenting his library - which he is not actually doing. In most cases all he is doing is making the comments in the code visible through some browser. Nothing wrong with this, but he's not really adding anything that one couldn't gain from just browsing the source code. d) If your source code isn't readable, you can create the impression that it's designed when it fact it isn't. That is it's useful for obscuring the fact that your code actually doesn't have any kind of design. So, for fans of Doxygen who have nothing else to do: a) Figure out how Doxygen customization works. I see this is huge slew of macros and settings which .... - well I don't know what it does. I guess it needs better documentation or perhaps design. b) Figure out how to express a concept in Doxygen and refer to it. c) Restrict usage of Doxygen to building xml reference pages for classes and class templates, functions and function templates. d) figure out how to meld this reference boost book using some other tool like quickbook, xml_mind, emacs or whatever. e) Be sure you make a good explanation so some naive person can create library documentation with your tools. e) If you get all this right - a tall order - be prepared to invest a lot of effort to evangelize your solution. This will be a very long and frustrating exercise. Or if you want to strike out on your own separate path - generally my own personal preference - you might consider an approach like caramel which would build on the idea of embedding boost book tags in comments and post processing the code. That's all I have to say about that. Robert Ramey