[Docs] Should remove_pointer doc make mention of and link to pointee doc?
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]? (I must say that I've been wholly ignorant of the latter in the couple of years that I've been using boost, since I always expected it to be under type_traits.) Additionally, it would be great if it was explained why it's not part of the type_traits library, since, at least I believe, it's not very obvious. 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.) Thanks, -Mostafa
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.
(I must say that I've been wholly ignorant of the latter in the couple of years that I've been using boost, since I always expected it to be under type_traits.) Additionally, it would be great if it was explained why it's not part of the type_traits library, since, at least I believe, it's not very obvious.
See above. If you can suggest specific wording changes to the docs that would clarify this stuff, I'd appreciate it.
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. -- David Abrahams BoostPro Computing http://boostpro.com
On Sat, 03 Jul 2010 08:47:22 -0700, David Abrahams <dave@boostpro.com> 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
participants (2)
-
David Abrahams -
Mostafa