Re: [boost] [Docs] Should remove_pointer doc make mention of and link to pointee doc?

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]>
wrote:

>
> 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  
>> [http://tinyurl.com/339n3f4]?
>
> 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  
place.

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  
library.

I would argue that in neither case would anyone think of looking in the  
iterator library.

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.

Sincerely,

-Mostafa