Re: The beauty of LATEX

On 21 October 2011 12:02, Paul A. Bristow <[email protected]> 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
_______________________________________________
Boost-docs mailing list
[email protected]
http://lists.boost.org/mailman/listinfo.cgi/boost-docs