[cfe-dev] Documenting Clang: question about how best to deliver the doc

[Paul A. Bristow]

> -----Original Message-----
> From: cfe-dev-bounces at cs.uiuc.edu [mailto:cfe-dev-bounces at cs.uiuc.edu] On Behalf Of Dmitri
> Gribenko
> Sent: Wednesday, August 21, 2013 5:17 AM
> To: Morrison, Michael
> Cc: cfe-dev at cs.uiuc.edu
> Subject: Re: [cfe-dev] Documenting Clang: question about how best to deliver the doc
> 
> On Tue, Aug 20, 2013 at 5:57 PM, Morrison, Michael <Michael_Morrison at playstation.sony.com> wrote:
> > Our main concern is picking the path forward that is most preferred by
> > the community.
> 
> If you decide to go with Doxygen, make sure to check that it supports all formatting you need.  In
> particular, check how tables, nested lists, and inline monospaced code works.

Just to add another possibility if you decide to use Doxygen-style comments.

Doug Gregor and others at Boost have developed a Doxygen interface from Boost's Quickbook to provide
a C++ reference section containing all the info in the Doxygen comments

\tparam, \param, \returns ...

Quickbook gives you most of the format control, automated hyperlinks, syntax colouring ... in your
textual documentation like tutorials, that you are likely to want.

Snippets of code can in included, so you can ensure that the code examples in the docs have been
compiled and run.

Lots of the biggest and newest libraries in Boost use this system and I think they look very nice.

So providing the Doxygen comments are there (the big task?), you can process them downstream in more
than one way.

HTH

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
+44 1539 561830  07714330204
pbristow at hetp.u-net.com