Boost logo

Boost :

Subject: Re: [boost] Doxygen documentation was Re: [review] Review of Outcome (starts Fri-19-May)
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-05-27 16:51:35


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

>


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk