Subject: Re: [boost] [Docs] Should remove_pointer doc make mention of and link to pointee doc?
From: Mostafa (mostafa_working_away_at_[hidden])
Date: 2010-07-03 16:08:16
On Sat, 03 Jul 2010 08:47:22 -0700, David Abrahams <dave_at_[hidden]>
> On Jul 3, 2010, at 4:33 AM, Mostafa wrote:
>> Hi all,
>> Shouldn't the remove_pointer doc [tinyurl.com/336cmlp] under
>> type_traits library make mention of and link to the pointee doc
> Nope. The latter is not really related. type_traits deal with basics
> of the C++ type system, like pointers. pointee deals with a
> higher-level idea that includes smart pointers and iterators.
Conceptually they are related. They both fall under the concept of "I want
something that will give me access to the dereferenced type", though one
being more specialized than the other. I'm not suggesting that pointee be
included in the type tratis library. Rather, I'm suggesting that for those
of us who skimmed the fact that "type_traits library only deals with
basics of the C++ type system" and went straight to it to find a
generalized remove_pointer, that we be given guidance on the proper place
to find it and a reminder of why it's not in type_traits in the first
It's not necessarily a question of wording, but one of navigation. There
are specifically two use cases I'm thinking of: novice boost user, and the
intermediate boost user.
I. Intermediate Boost User
For the intermediate boost user, I would argue the first place they would
look would be in type_traits. And since they're intermediate, they'll skip
the Background and Introduction and go straight to the Alphabetical
Reference, skimming it looking for something that will give them the
"pointed-to-type", and inevitably they will discover remove_pointer.
II. Novice Boost User
They would most likely skim "Libraries Listed Alphabetically" looking for
a library that might provide what they want, and they would most probably
spot and investigate type_traits and, as a last resort, the utility
I would argue that in neither case would anyone think of looking in the
BTW, the only way I found about pointee was first trying the docs, and
then Google. In fact, it took a few tries on Google, even then it wasn't
direct, rather it took me to a similar discussion you and Jeff Mirwaisi
had back in 2004, and from that I was able to find what I wanted.
>> One last question, why is pointee under the iterator library docs, when
>> it also deals with shared_ptrs? Shouldn't it fall under the utility
>> doc? (The iterator doc would be the last place I would look if I wanted
>> to find something on shared_ptrs.)
> Maybe, but it was built as part of the implementation of
> indirect_iterator, so that's where it ended up.
I would argue that that's not a very good reason for keeping it there.
Just as code that started out in library Y can be factored out into its
own library once its scope is no longer limited to library Y, then so
should documentation. pointee is no longer limited in scope to the
iterator library and last I checked "pointee.hpp" is not placed in
"boost/iterator" but in "boost".
The above are my suggestions on how to improve navigability.