Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Mateusz Łoskot (mateusz_at_[hidden])
Date: 2011-10-21 11:51:24

On 21 October 2011 12:02, Paul A. Bristow <pbristow_at_[hidden]> wrote:
> If we have a C++ function in a header, and provide some 'concept' info in Doxygen syntax inside a
> C++ comment.
>
> /*!
> Â  Â  Â  nontype template function that just returns the template value.
> Â  Â  Â \tparam size is a constant integer argument.
> Â  Â  Â \returns constant integer size always.
> Â  Â  Â \pre No preconditions.
> Â  Â  Â \post No side effects.
> Â  Â  Â \throws Never.
> Â  Â  Â \warning This is not a very useful function.
> Â  Â  Â \see More useful functions.
> Â */
> Â template <int size>
> Â int template_parameter_size()
> Â {
> Â  Â return size;
> Â }
>
> Could we invent a better syntax? Â I'm sceptical - it seems so simple.

Doxygen is greedy (in regexp terms).
To make Doxygen greedy, you need to juggle comment styles what leads to mess.
Also, simplicity has its limits

// Comment not dedicated to end-user documentation or API reference.
// [function template_parameter_size
//     nontype template function that just returns the template value.
//     [parameter size is a constant integer argument
//          [requires AnyNumberConcept<size>]]
//     [argument Function expects no arguments]
//     [return constant integer size always.
//          [requires AnyNumberConcept<size>]]
//     [precond No preconditions]
//     [postcond No side effects]
//     [nothrow]
//     [warning This is not a very useful function]
//     [note More useful functions]
// ]
// Does not compile with X. (Here another internal
// comment not shown in API reference.)
template <int size>
int template_parameter_size()
{
   return size;
}

Another rough examples

[concept BinaryFunction
   [refines Assignable]
   [refinedby None]
   [related UnaryFunction]
   [model `Result (*)(X, Y)` Pointer to function...] [/ model name
wrapped with `` because contains spaces]
   [notation
      [F A type that is a model of BinaryFunction] [/no need to wrap F
as `F` because it's solid token, no white spaces]
      [X The first argument type of F]
      [Result The result type of F]]
   [expression f(x,y) Function call
      [requires ...]
      [returns ...]
      [precond ...]
      [semantic ....]
      [postcond ...]]
   [expression ...]
]

[concept DefaultConstructivle
   [refines None]
   [notation
      [X A type that is a model of DefaultConstructivle]
      [x Object of type X]]
   [model int]
   [model std::vector<T>]
]

What I like is reading such quickbook-wrapped comments is well aligned
to reading natural language,
With [] removed, story in English language remains.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
Member of ACCU, http://accu.org