Re: [boost] [Concepts] Definition. Was [GSoC] [Boost.Hana] Formal review request

Subject: Re: [boost] [Concepts] Definition. Was [GSoC] [Boost.Hana] Formal review request
From: Robert Ramey (ramey_at_[hidden])
Date: 2014-08-05 18:44:43

Roland Bock-2 wrote
> I have my doubts though, that
> the STL documentation structure can be used as-is in a reasonable way
> for every library.
> 
> For instance I would not know how to do that for sqlpp11, but I would
> love to discuss it over a beer at CppCon.
> 
> As of now, I'd say that the STL documentation provides a good starting
> point for the documentation structure of most libraries (maybe all, I
> don't know). But adaptations might be required to make it fit to
> specific libraries.

I make my case in
http://rrsd.com/blincubator.com/requirements_documentation/

Tutorial documentation of course is another issue so exclude that for now.

Basically reference documentation contains a list of:

named type constraints (concepts)
types and parameterized types
functions

The "outline" link shows what I think anyone who makes a C++ library
should fill in to get good documentation (and properly factored code also!).

I can't prove it, but I believe this template is effective for every C++
library.

I'm looking forward to a free beer.  In the meantime, you might consider
taking a look a the section above as well as the Simple Tools section 
regarding documentation.  The reference docs would be built by
taking every class and template and filling out the corresponding forms
for types.  Part of the template docs are parameter requirements.  At
some point you'll find that your repeating yourself and decide to factor
out common requirements and naming them - these will be your 
you named type requirements.  After a while, you'll likely see that
you have "too" many "named type requirements" and you might
go back and tweak your code to diminish the multiplicity of named
type requirements.  When you get back with this, your library will
be smaller, simpler and easier to understand and use.

Take a crack at this before we talk - 

Robert Ramey

--
View this message in context: http://boost.2283326.n4.nabble.com/Concepts-Definition-Was-GSoC-Boost-Hana-Formal-review-request-tp4666011p4666100.html
Sent from the Boost - Dev mailing list archive at Nabble.com.