Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-10-22 08:10:42

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Joel de Guzman
> Sent: Saturday, October 22, 2011 2:58 AM
> To: boost-docs_at_[hidden]
> Subject: Re: [Boost-docs] The beauty of LATEX
> 
> On 10/21/2011 7:51 PM, Mateusz Łoskot wrote:
> 
> > // 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.
> 
> I Luv it!

So *will* I - when it works!

Rockstar docs ;-)

I'm not sure that should stop us using the existing toolchain until it does (even if it chokes on oddball libraries like Boost.Parameter  ;-)

Paul

PS Glad to hear that people who know more than think (part of?) Clang could be a good 'parser' of the C++ structure. It should be free of all the annoying pickiness about location of comments that Doxygen's parser suffers from (or rather that the user suffer from!).

PPS Does this mean we can freely choose between putting comments embedded in the C++ files, and putting the same docs in separate .qbk files?

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]