On 5/27/17 9:19 AM, Rene Rivera via Boost wrote:
On Sat, May 27, 2017 at 11:09 AM, Robert Ramey via Boost <
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.
You can also just include Quickbook docs in your source and include those in a coherent manner in your regular quickbook docs. Since there's no "automatic" class, function, etc. mechanics it forces you to write real documentation in your source where it's also accessible to people just browsing code. It also make it easier for people to contribute to your project as they submit docs along with code changes. This approach has been essential in getting a good number of external submissions to Predef, for example.
So that's even a fourth way. and there are probably more. I would like to emphasize that this is not an easy task. It's not just a question inserting a new, clever and cool little tool into the documentation tool chain. It's about changing the developer mindset about what documentation is and should be. The reason this is very, very difficult is that everyone thinks that they're not the problem - that other people are. But if that were true, there would be no complaints about documentation. It's also my view that difficulties in writing documentation reflect bad design decisions. But I'm having problems convincing developers of that. (I wanted to move this to a root thread but it's not showing that way on my news server output) Robert Ramey