Re: [boost] [type_erasure] Review started (July 18-27, 2012)

Subject: Re: [boost] [type_erasure] Review started (July 18-27, 2012)
From: Julien Nitard (julien.nitard_at_[hidden])
Date: 2012-07-30 11:08:43

Hi

[ ... ]

>> For instance, if removing this feature or simplifying the construction
>> would allow removing the possibility to construct a "reference any"
>> from a "reference-to-const any" I'd choose to remove the bug.
>
> This shouldn't be possible.  Do you have
> a test case?

No, it's not a bug I found, you mentioned that limitation in the doc,
"Using References", last 3 sentences.

[ snipped rant about lack of doc in the code ]

> The vtable isn't terribly complex.  It's essentially
> a statically initialized fusion::map.
[...]
> A lot of the library internals are similar in
> that they're essentially simple components
> with a lot of preprocessor baggage around them.
> The only real algorithmic complexity is in
> normalize.hpp.

Others have found the code to be easy enough to read, so I'll take the
blame for not being fluent enough for reading this kind of code
quickly. I still think that more comments the better ;) I'll give it a
second try since the review was extended.

> I can make sure that the library doesn't
> produce deep template instantiation
> backtraces in most cases.  There are
> a few cases where a static assertion
> would help too.

Please do !

[ ... ]

>> Right now it's more or less backward. Very advanced concepts like
>> placeholder types jointly capture variables are introduced before
>> showing how to make your own concept and what's a concept by the way.
>>
>
> The "Functions with multiple arguments" appears
> early because it introduces placeholders, which
> are used in many sections.

Yes but those sections are already advanced, I think more are needed before.

>
> Any order is going to be somewhat problematic,
> because of the way all the core components of the
> library are connected.  Whatever I introduce
> first is going to depend on things that aren't
> explained until later.

You don't have to introduce every thing at once. You will have to
ignore things you consider important at first to draw people into
reading the documentation not lose them after 5 sentences of meta
concepts they've never heard of (quite likely for this library). That
is unless you only care about advanced users, but the library is so
good it would be a pity.

> I think the first examples in the docs need
> to be based on
> - only predefined concepts
> - no placeholders used explicitly
> - capture by value

To show only predefined concepts is ignoring that a great deal of
interfaces don't use any operators and do not require any
construction, copy or deletion semantics which is what the predefined
concepts are about. The main way I see myself using TypeErasure is by
creating concept and then adapting types.

After rewriting this paragraph about 20 times I think that the order
for the capturing mode isn't that relevant as long as both get their
share of love early on.
It appears more and more clearly to me that there are two ways of
using TypeErasure:
 - values and operators, that comes from the
boost::any/function/any_iterator adobe::poly origins. These are for
libraries developers such as boost or stl coders.
 - references and methods, for people who have long been contaminated
by other languages as part of former experiences like myself. These
are for more concrete uses, i.e. I need a socket and a connect
function that takes an ip and a port in the same format.
I guess the current documentation is biased on the first one right now
but shouldn't. It is my strong belief that more coders use the 2nd
paradigm.
What's interesting it's now it's easy to mix them when ever needed ;)

>>  - I'd rewrite the "Concept Definitions" page. You define 3 kinds of
>> high level concepts first, then explain what a primitive concept is.
>> I'd keep the placeholder stuff for a different section.
>>
> In this section, I'm trying to specify exactly
> what makes a valid concept.  It's a bit hard
> to do that without discussing placeholders.
> Also, I'm more focussed on precision than
> on readability here.  Informal descriptions
> can go in earlier sections.

Then split it into two parts. A "white lie" introduction and then a
full spec for those willing/needing to know the details.

Some additional comments not in my review:
Two missing concepts that you could consider: ranges (well actually
more than one by itself) and copy-on-write. Not a priority obviously.

Thanks again for all those efforts,

Julien