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

Subject: [Boost-docs] FW: [cfe-dev] Documenting Clang: question about how best to deliver the doc
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-08-29 09:13:34

I've copied the posting below because it shows that Doxygen comments syntax are being even more widely used to add documentation of code (as opposed to writing tutorial and other descriptive text).
 
Doxygen comments are post-processed to produce a C++ Reference section in many Boost program docs prepared using Quickbook.  
 
I suggest that this is a good method for future proposed libraries.
 
In case you are not familiar with Doxygen, 
 
http://www.stack.nl/~dimitri/doxygen/manual/index.html
 
here is a silly example to give the flavour of the comments (they start with the backslash trip character and are within C/C++ comments with an added !).
 
template <typename T>
int donowt(int I, char j)
  { /*!  The ! shows that this is a Doxygen-syntax comment.
       Non-member free function that does nowt useful at all describing the function.
      \tparam T unused template parameter.
      \param i is an argument that is ignored completely.
      \param j Another argument.
      \pre No preconditions.
      \post No side effects.
      \returns -1 always.
      \throws std::exception if the unthinkable happens.
      \sa  See also another function.
  */
    return -1;
  } //   int donowt(int i)
 
Of course, the value from all this comes from the quality of the *information provided as comments*, describing the use of the parameters, templates, pre and post conditions (documenting but not enforcing concepts) and returns...
 
Doxygen also analyses the code (now optionally using the Clang compiler - it used to get confused by some code, especially code that didn't compile!) and provides many cross-referencing links automatically, a great benefit to the authors and the readers.
 
Doxygen remains under active development thanks to  <http://www.stack.nl/%7Edimitri/doxygen/index.html> Dimitri van Heesch.  It is Open-Source and entirely free and very widely used for several languages.
 
Paul
 
---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]
 
 
 
From: cfe-dev-bounces_at_[hidden] [mailto:cfe-dev-bounces_at_[hidden]] On Behalf Of Morrison, Michael
Sent: Tuesday, August 27, 2013 10:40 PM
To: cfe-dev_at_[hidden]
Subject: Re: [cfe-dev] Documenting Clang: question about how best to deliver the doc
 
Thanks to everyone on this thread who replied to our query about what approach to take for our Clang documentation.  Your thoughtful comments were very helpful to our understanding of the issues and of the preferences of the community.  We’ve reviewed your responses to the options that we proposed, and we’ve decided to pursue the following option:
 
> 1a)  Maintain the documentation in Doxygen.  Any other formats required (HTML, XML, reST/Sphynx,  and so on) can be generated on-the-fly from the Doxygen comments as needed.
 
We have a good idea about how to proceed with this option, and we expect that we can begin submitting our updated Doxygen documentation later this summer. 
 
Cheers,
Michael