Add pointer_to_other.adoc

doc/smart_ptr/intrusive_ptr.adoc

@@ -13,7 +13,7 @@ http://www.boost.org/LICENSE_1_0.txt
 :toc-title:
 :idprefix: intrusive_ptr_
 
-## Introduction
+## Description
 
 The `intrusive_ptr` class template stores a pointer to an object with an embedded reference count.
 Every new `intrusive_ptr` instance increments the reference count by using an unqualified call to the
@@ -38,6 +38,8 @@ As a general rule, if it isn't obvious whether `intrusive_ptr` better fits your
 
 ## Synopsis
 
+`intrusive_ptr` is defined in `<boost/smart_ptr/intrusive_ptr.hpp>`.
+
 ```
 namespace boost
 {

doc/smart_ptr/pointer_to_other.adoc

@@ -1,5 +1,6 @@
 ////
-Copyright 2017 Peter Dimov
+Copyright 2005, 2006 Ion Gaztañaga
+Copyright 2005, 2006, 2017 Peter Dimov
 
 Distributed under the Boost Software License, Version 1.0.
 
@@ -13,3 +14,103 @@ http://www.boost.org/LICENSE_1_0.txt
 :toc-title:
 :idprefix: pointer_to_other_
 
+## Description
+
+The `pointer_to_other` utility provides a way, given a source pointer type, to obtain a pointer of the same type
+to another pointee type.
+
+There is test/example code in link:../../test/pointer_to_other_test.cpp[pointer_to_other_test.cpp].
+
+## Rationale
+
+When building pointer independent classes, like memory managers, allocators, or containers, there is often a need to
+define pointers generically, so that if a template parameter represents a pointer (for example, a raw or smart pointer
+to an `int`), we can define another pointer of the same type to another pointee (a raw or smart pointer to a `float`.)
+
+```
+template <class IntPtr> class FloatPointerHolder
+{
+    // Let's define a pointer to a float
+
+    typedef typename boost::pointer_to_other
+        <IntPtr, float>::type float_ptr_t;
+
+    float_ptr_t float_ptr;
+};
+```
+
+## Synopsis
+
+`pointer_to_other` is defined in `<boost/smart_ptr/pointer_to_other.hpp>`.
+
+```
+namespace boost
+{
+
+template<class T, class U> struct pointer_to_other;
+
+template<class T, class U,
+  template <class> class Sp>
+    struct pointer_to_other< Sp<T>, U >
+{
+   typedef Sp<U> type;
+};
+
+template<class T, class T2, class U,
+  template <class, class> class Sp>
+    struct pointer_to_other< Sp<T, T2>, U >
+{
+    typedef Sp<U, T2> type;
+};
+
+template<class T, class T2, class T3, class U,
+  template <class, class, class> class Sp>
+    struct pointer_to_other< Sp<T, T2, T3>, U >
+{
+    typedef Sp<U, T2, T3> type;
+};
+
+template<class T, class U>
+  struct pointer_to_other< T*, U > 
+{
+    typedef U* type;
+};
+
+} // namespace boost
+```
+
+If these definitions are not correct for a specific smart pointer, we can define a specialization of `pointer_to_other`.
+
+## Example
+
+```
+// Let's define a memory allocator that can
+// work with raw and smart pointers
+
+#include <boost/pointer_to_other.hpp>
+
+template <class VoidPtr>
+class memory_allocator
+{
+    // Predefine a memory_block
+
+    struct block;
+
+    // Define a pointer to a memory_block from a void pointer
+    // If VoidPtr is void *, block_ptr_t is block*
+    // If VoidPtr is smart_ptr<void>, block_ptr_t is smart_ptr<block>
+
+    typedef typename boost::pointer_to_other
+        <VoidPtr, block>::type block_ptr_t;
+
+    struct block
+    {
+        std::size_t size;
+        block_ptr_t next_block;
+    };
+
+    block_ptr_t free_blocks;
+};
+```
+
+As we can see, using `pointer_to_other` we can create pointer independent code.

doc/smart_ptr/scoped_array.adoc

@@ -43,6 +43,8 @@ The class template is parameterized on `T`, the type of the object pointed to.
 
 ## Synopsis
 
+`scoped_array` is defined in `<boost/smart_ptr/scoped_array.hpp>`.
+
 ```
 namespace boost
 {