Index: code/branches/doc/src/libraries/util/SharedPtr.h
===================================================================
--- code/branches/doc/src/libraries/util/SharedPtr.h	(revision 7290)
+++ code/branches/doc/src/libraries/util/SharedPtr.h	(revision 7327)
@@ -27,4 +27,121 @@
  */
 
+/**
+    @defgroup SharedPtr SharedPtr<T>
+    @ingroup Util Object
+*/
+
+/**
+    @file
+    @ingroup Util SharedPtr
+    @brief Definition of the SharedPtr template that is used to manage pointers.
+
+    @anchor SharedPtrExample
+
+    The orxonox::SharedPtr template can be used to manage a pointer to an object
+    that was created with new. The SharedPtr acts like the pointer itself, but it
+    keeps track of the number of references to it. If all references are removed,
+    SharedPtr deletes the managed object automatically.
+
+    Example:
+
+    Classic implementation using new and delete:
+    @code
+    void someFunction()
+    {
+        MyClass* object = new MyClass();            // Create a new instance of MyClass
+
+        object->myFunction();                       // Calls MyClass::myFunction()
+
+        delete object;                              // Delete the object at the end of the scope
+    }
+    @endcode
+
+    The same function using SharedPtr:
+    @code
+    void someFunction()
+    {
+        SharedPtr<MyClass> object = new MyClass();  // Create a new instance of MyClass and store its pointer in a SharedPtr
+
+        object->myFunction();                       // Calls MyClass::myFunction()
+
+    }                                               // At the end of the scope, the SharedPtr is destroyed. Because no other SharedPtrs
+                                                    // point at the object, the object itself is also destroyed automatically
+    @endcode
+
+    This is especially handy if you do not know what will happen with an object that was
+    created with new, for example if you pass it to another object. If multiple instances
+    share a pointer to the same object, none of these instances can delete the object
+    without interfering with the other instances. But if none of the instances destroy the
+    object, it will never be destroyed and results in a memory leak. With a SharedPtr
+    however you don't have to think about destroying the object, because the SharedPtr
+    itself keeps track of the references.
+
+    Example:
+
+    Classic implementation using new and delete:
+    @code
+    class OtherClass                                    // Declaration of some class
+    {
+        public:
+            OtherClass(MyClass* object)                 // Constructor
+            {
+                this->object_ = object;                 // Assigns the pointer to the member variable object_
+            }
+
+            ~OtherClass()                               // Destructor
+            {
+                ???                                     // What to do with object_?
+            }
+
+        private:
+            MyClass* object_;                           // A pointer to the object
+    };
+
+    void someFunction()
+    {
+        MyClass* object = new MyClass();                // Create a new instance of MyClass
+
+        OtherClass* other1 = new OtherClass(object);    // Create an instance of OtherClass and pass the object pointer
+        OtherClass* other2 = new OtherClass(object);    // "
+        OtherClass* other3 = new OtherClass(object);    // "
+
+        ???                                             // What happens with object now?
+    }
+    @endcode
+
+    If you use SharedPtr<MyClass> instead of a classic MyClass* pointer, the instance of
+    MyClass would be automatically destroyed if all instances of OtherClass are destroyed.
+    You don't need any code in the destructor and you can completely forget about the
+    object, because its managed by the SharedPtr.
+
+    The same code using SharedPtr:
+    @code
+    class OtherClass                                        // Declaration of some class
+    {
+        public:
+            OtherClass(const SharedPtr<MyClass>& object)    // Constructor
+            {
+                this->object_ = object;                     // Assigns the pointer to the member variable object_
+            }
+
+        private:
+            SharedPtr<MyClass> object_;                     // A SharedPtr to the object
+    };
+
+    void someFunction()
+    {
+        SharedPtr<MyClass> object = new MyClass();          // Create a new instance of MyClass
+
+        OtherClass* other1 = new OtherClass(object);        // Create an instance of OtherClass and pass the object pointer
+        OtherClass* other2 = new OtherClass(object);        // "
+        OtherClass* other3 = new OtherClass(object);        // "
+
+    }                                                       // The SmartPtr "object" is destroyed at the end of the scope,
+                                                            // but the three instances of OtherClass keep the object alive
+                                                            // until they are all destroyed.
+    @endcode
+*/
+
 #ifndef _SharedPtr_H__
 #define _SharedPtr_H__
@@ -39,36 +156,55 @@
 namespace orxonox
 {
-    class SharedCounter
-    {
-        public:
-            SharedCounter() : count_(1) {}
-            virtual void destroy() = 0;
-
-            int count_;
-    };
-
-    template <class T>
-    class SharedCounterImpl : public SharedCounter
-    {
-        public:
-            SharedCounterImpl(T* pointer) : pointer_(pointer) {}
-
-            void destroy()
-            {
-                delete this->pointer_;
-            }
-
-        private:
-            T* pointer_;
-    };
-
-    _UtilExport SmallObjectAllocator& createSharedCounterPool();
-
-    FORCEINLINE SmallObjectAllocator& getSharedCounterPool()
-    {
-        static SmallObjectAllocator& instance = createSharedCounterPool();
-        return instance;
+    namespace detail
+    {
+        /// BaseClass of SharedCounterImpl, has a counter that is initialized with 1
+        class SharedCounter
+        {
+            public:
+                SharedCounter() : count_(1) {}
+                virtual void destroy() = 0;
+
+                int count_;
+        };
+
+        /// Child class of SharedCounter, keeps a pointer to an object of type T that can be destroyed with destroy()
+        template <class T>
+        class SharedCounterImpl : public SharedCounter
+        {
+            public:
+                SharedCounterImpl(T* pointer) : pointer_(pointer) {}
+
+                void destroy()
+                {
+                    delete this->pointer_;
+                }
+
+            private:
+                T* pointer_;
+        };
+
+        _UtilExport SmallObjectAllocator& createSharedCounterPool();
+
+        FORCEINLINE SmallObjectAllocator& getSharedCounterPool()
+        {
+            static SmallObjectAllocator& instance = createSharedCounterPool();
+            return instance;
+        }
     }
 
+    /**
+        @brief The SharedPtr template is a utility to manage pointers to an object.
+        @param T The type of the managed object
+
+        SharedPtr acts like a real pointer, except that it keeps track of the number of
+        references to the object. If the the number of references drops to zero, the
+        object is destroyed automatically.
+
+        @see See @ref SharedPtrExample "this description" for some examples and more information.
+
+        @note The number of references is stored in a separate object that is shared
+        among all instances of SharedPtr that point to the same pointer. This object is
+        also responsible for destroying the pointer if the reference counter becomes zero.
+    */
     template <class T>
     class SharedPtr
@@ -78,17 +214,20 @@
 
         public:
+            /// Default constructor, the pointer is set to NULL.
             inline SharedPtr() : pointer_(0), counter_(0)
             {
             }
 
+            /// Constructor, creates a SharedPtr that points to @a pointer, increments the counter.
             inline SharedPtr(T* pointer) : pointer_(pointer), counter_(0)
             {
                 if (this->pointer_)
                 {
-                    void* chunk = getSharedCounterPool().alloc();
-                    this->counter_ = new (chunk) SharedCounterImpl<T>(this->pointer_);
+                    void* chunk = detail::getSharedCounterPool().alloc();
+                    this->counter_ = new (chunk) detail::SharedCounterImpl<T>(this->pointer_);
                 }
             }
 
+            /// Copy-constructor, this SharedPtr now points to the same object like the other SharedPtr, increments the counter.
             inline SharedPtr(const SharedPtr& other) : pointer_(other.pointer_), counter_(other.counter_)
             {
@@ -97,4 +236,5 @@
             }
 
+            /// Copy-constructor for SharedPtr with another template agument, increments the counter.
             template <class O>
             inline SharedPtr(const SharedPtr<O>& other) : pointer_(other.pointer_), counter_(other.counter_)
@@ -104,4 +244,5 @@
             }
 
+            /// Destructor, decrements the counter and deletes the object if the counter becomes zero.
             inline ~SharedPtr()
             {
@@ -113,9 +254,10 @@
                     {
                         this->counter_->destroy();
-                        getSharedCounterPool().free(this->counter_);
+                        detail::getSharedCounterPool().free(this->counter_);
                     }
                 }
             }
 
+            /// Assigns a new object, decrements the counter of the old object, increments the counter of the new object.
             inline SharedPtr& operator=(const SharedPtr& other)
             {
@@ -124,4 +266,5 @@
             }
 
+            /// Assigns a new object with another template argument, decrements the counter of the old object, increments the counter of the new object.
             template <class O>
             inline SharedPtr& operator=(const SharedPtr<O>& other)
@@ -131,4 +274,5 @@
             }
 
+            /// Casts the pointer to another type
             template <class O>
             inline SharedPtr<O> cast() const
@@ -138,4 +282,5 @@
             }
 
+            /// Overloaded -> operator, returns the pointer to the managed object.
             inline T* operator->() const
             {
@@ -144,4 +289,5 @@
             }
 
+            /// Overloaded * operator, returns a reference ot the managed object.
             inline T& operator*() const
             {
@@ -150,4 +296,5 @@
             }
 
+            /// Returns the pointer to the managed object.
             inline T* get() const
             {
@@ -155,4 +302,5 @@
             }
 
+            /// Returns true if the pointer is not NULL.
             inline operator bool() const
             {
@@ -160,4 +308,5 @@
             }
 
+            /// Swaps the pointer and the counter of two instances of SharedPtr with the same template argument.
             inline void swap(SharedPtr& other)
             {
@@ -167,5 +316,6 @@
 
         private:
-            inline SharedPtr(T* pointer, SharedCounter* counter) : pointer_(pointer), counter_(counter)
+            /// Private constructor, used by the cast() function.
+            inline SharedPtr(T* pointer, detail::SharedCounter* counter) : pointer_(pointer), counter_(counter)
             {
                 if (this->pointer_)
@@ -173,8 +323,39 @@
             }
 
-            T* pointer_;
-            SharedCounter* counter_;
+            T* pointer_;                        ///< A pointer to the managed object of type @a T
+            detail::SharedCounter* counter_;    ///< A pointer to the shared reference counter
     };
 
+    /**
+        @brief A child class of SharedPtr, used to reflect the hierarchy of the underlying class @a T.
+        @param T The type of the managed object
+        @param Parent The type of the SharedPtr that manages the parent class of @a T
+
+        This class is used to reflect the hierarchy of the underlying class @a T.
+        For example the @c Functor classes: While a @c Functor* pointer would be managed by
+        @c SharedPtr<Functor>, the child class @c FunctorStatic is managed by the class
+        <tt>SharedChildPtr<FunctorStatic, SharedPtr<Functor> ></tt>.
+
+        The second template argument @a Parent is used as the parent class of
+        SharedChildPtr. This means that each instance of <tt>SharedChildPtr<T, Parent></tt>
+        can be upcasted to @c Parent.
+
+        So for example this works:
+        @code
+        SharedChildPtr<FunctorStatic, SharedPtr<Functor> > functorStatic = createFunctor(&MyClass::myStaticFunction);
+        SharedPtr<Functor> functor = functorStatic;
+        @endcode
+
+        @note There are some typedefs and more to make the usage of SharedChildPtr easier
+        for the classes Functor and Executor. See FunctorPtr.h and ExecutorPtr.h. The above
+        example could thus be simplified the following way:
+        @code
+        FunctorStaticPtr functorStatic = createFunctor(&MyClass::myStaticFunction);
+        FunctorPtr functor = functorStatic;
+        @endcode
+
+        @see See SharedPtr for more information about the base class SharedPtr.
+        @see See @ref SharedPtrExample "this description" for some examples about how to use SharedPtr.
+    */
     template <class T, class Parent>
     class SharedChildPtr : public Parent
