adding documentationHEADmaster

3 files changed, 508 insertions, 6 deletions

diff --git a/ue5/array.hpp b/ue5/array.hpp
index 0acd37d..a78ff56 100644
--- a/ue5/array.hpp
+++ b/ue5/array.hpp
@@ -1,3 +1,10 @@
+/**
+ * @module array
+ * @author Guenther Neuwirth (0626638), Manuel Mausz (0728348)
+ * @brief  Class template array
+ * @date   13.06.2009
+ */
+
 #ifndef ARRAY_H
 #define ARRAY_H
 
@@ -10,72 +17,208 @@
 
 namespace Ti
 {
+  /**
+   * @class array
+   *
+   * Array defines a class template for storing fixed-size sequences of objects.
+   */
   template<typename T, std::size_t N>
     struct array
     {
+      /** lvalue of T */
       typedef T& reference;
+      /** constant lvalue of T */
       typedef const T& const_reference;
+      /** iterator type whose value type is T */
       typedef T* iterator;
+      /** constant iterator type whose value type is T */
       typedef const T* const_iterator;
+      /** unsigned integral type */
       typedef std::size_t size_type;
 
+      /* we don't suppport zero-sized arrays */
       static_assert(N != 0, "array<T, 0> not allowed");
 
+      /**
+       * @method fill
+       * @brief  Fills container with elements of u
+       * @param  u  object to fill array with
+       * @return return N
+       * @globalvars none
+       * @exception  none
+       * @pre  requires CopyAssignable<T> void fill(const T& u)
+       * @post none
+       */
       void fill(const T& u)
       {
         std::fill_n(begin(), N, u);
       }
 
-      void swap(array<T,N> & other)
+      /**
+       * @method swap
+       * @brief  Exchanges the contents of *this and other.
+       * @param  other  object to swap with
+       * @return -
+       * @globalvars none
+       * @exception  none
+       * @pre  none
+       * @post none
+       */
+      void swap(array<T,N>& other)
       {
         std::swap_ranges(begin(), end(), other.begin());
       }
 
+      /**
+       * @method begin
+       * @brief  Get an iterator referring to the first element in the container
+       * @param  -
+       * @return iterator referring to the first element in the container.
+       * @globalvars none
+       * @exception  none
+       * @pre  none
+       * @post none
+       */
       iterator begin()
       {
         return m_data;
       }
 
+      /**
+       * @method begin
+       * @brief  Get a constant iterator referring to the first element in the
+       *         container
+       * @param  -
+       * @return constant iterator referring to the first element in the container.
+       * @globalvars none
+       * @exception  none
+       * @pre  none
+       * @post none
+       */
       const_iterator begin() const
       {
         return m_data;
       }
 
+      /**
+       * @method end
+       * @brief  Get an iterator which is the past-the-end value for the container.
+       * @param  -
+       * @return iterator which is the past-the-end value for the container
+       * @globalvars none
+       * @exception  none
+       * @pre  none
+       * @post none
+       */
       iterator end()
       {
         return m_data + N;
       }
 
+      /**
+       * @method end
+       * @brief  Get a constant iterator which is the past-the-end value for the
+       *         container.
+       * @param  -
+       * @return constant iterator which is the past-the-end value for the container
+       * @globalvars none
+       * @exception  none
+       * @pre  none
+       * @post none
+       */
       const_iterator end() const
       {
         return m_data + N;
       }
 
+      /**
+       * @method size
+       * @brief  Get number of elements in the container
+       * @param  -
+       * @return return N
+       * @globalvars none
+       * @exception  none
+       * @pre  none
+       * @post none
+       */
       size_type size() const
       {
         return N;
       }
 
+      /**
+       * @method max_size
+       * @brief  Get maximal number of elements which fit into the container
+       * @param  -
+       * @return return N
+       * @globalvars none
+       * @exception  none
+       * @pre  none
+       * @post none
+       */
       size_type max_size() const
       {
         return N;
       }
 
+      /**
+       * @method empty
+       * @brief  Check if container is empty
+       * @param  -
+       * @return always false
+       * @globalvars none
+       * @exception  none
+       * @pre  none
+       * @post none
+       */
       bool empty() const
       {
         return false; /* size() == 0 */
       }
 
+      /**
+       * @method operator[]
+       * @brief  operator []
+       * @param  n  position of an element in the array
+       * @return reference to the element at position n in the container
+       * @globalvars none
+       * @exception  none
+       * @pre  none
+       * @post none
+       */
       reference operator[](size_type n)
       {
         return m_data[n];
       }
 
+      /**
+       * @method operator[]
+       * @brief  operator []
+       * @param  n  position of an element in the array
+       * @return constant reference to the element at position n in the container
+       * @globalvars none
+       * @exception  none
+       * @pre  none
+       * @post none
+       */
       const_reference operator[](size_type n) const
       {
         return m_data[n];
       }
 
+      /**
+       * @method at
+       * @brief  Get reference to the element at position n
+       * @param  n  position of an element in the array
+       * @return reference to the element at position n in the container.
+       *         The difference between this member function and member operator
+       *         function operator[] is that at signals if the requested
+       *         position is out of range by throwing an out_of_range exception.
+       * @globalvars none
+       * @exception  out_of_range
+       * @pre  none
+       * @post none
+       */
       reference at(size_type n)
       {
         if (n >= N)
@@ -83,6 +226,19 @@ namespace Ti
         return m_data[n];
       }
 
+      /**
+       * @method at
+       * @brief  Get constant reference to the element at position n
+       * @param  n  position of an element in the array
+       * @return constant reference to the element at position n in the container.
+       *         The difference between this member function and member operator
+       *         function operator[] is that at signals if the requested
+       *         position is out of range by throwing an out_of_range exception.
+       * @globalvars none
+       * @exception  out_of_range
+       * @pre  none
+       * @post none
+       */
       const_reference at(size_type n) const
       {
         if (n >= N)
@@ -90,22 +246,41 @@ namespace Ti
         return m_data[n];
       }
 
+      /**
+       * @method data
+       * @brief  Check if container is empty
+       * @param  -
+       * @return returns enclosed array
+       * @globalvars none
+       * @exception  none
+       * @pre  none
+       * @post none
+       */
       T* data()
       {
         return m_data;
       }
 
       private:
+        /** enclosed array */
         T m_data[N];
     };
 
-  /* std::move returns lvalue as rvalue */
+  /**
+   * @method make_array
+   * @brief  Get an rvalue of an empty array
+   * @param  none
+   * @return rvalue of an empty array
+   * @globalvars none
+   * @exception  none
+   * @pre  none
+   * @post none
+   */
   template<typename T, std::size_t N>
     array<T, N>&& make_array()
   {
     return std::move(array<T, N>());
   }
-
 } // namespace
 
 #endif
diff --git a/ue5/mean_mark.hpp b/ue5/mean_mark.hpp
index e07aedc..614a671 100644
--- a/ue5/mean_mark.hpp
+++ b/ue5/mean_mark.hpp
@@ -1,3 +1,10 @@
+/**
+ * @module mean_mark
+ * @author Guenther Neuwirth (0626638), Manuel Mausz (0728348)
+ * @brief  Templates for mean_mark, mean_mark_student, remove_greater
+ * @date   13.06.2009
+ */
+
 #ifndef MEAN_MARK_H
 #define MEAN_MARK_H
 
@@ -9,7 +16,18 @@
 
 namespace Ti
 {
-
+  /**
+   * @method mean_mark
+   * @brief  computes mean mark in the range [first,last)
+   * @param  first  forward iterator to the initial positions in a sequence
+   * @param  last   forward iterator to the final positions in a sequence
+   * @return computed mean mark
+   * @globalvars none
+   * @exception  none
+   * @pre  all objects in the sequence must have a method mark returning a type
+   *       convertible to double
+   * @post none
+   */
   template <typename Iter>
     double mean_mark(Iter first, Iter last)
     {
@@ -23,6 +41,19 @@ namespace Ti
       return (count == 0) ? 0 : result / count;
     }
 
+  /**
+   * @method mean_mark_student
+   * @brief  computes mean mark of objects of type Student in the range [first,last)
+   *         (using RTTI)
+   * @param  first  forward iterator to the initial positions in a sequence
+   * @param  last   forward iterator to the final positions in a sequence
+   * @return computed mean mark of objects of type Student
+   * @globalvars none
+   * @exception  none
+   * @pre  All objects in the sequence must have a method mark returning a type
+   *       convertible to double. And type Stundent must exist
+   * @post none
+   */
   template <typename Iter>
     double mean_mark_student(Iter first, Iter last)
     {
@@ -41,6 +72,23 @@ namespace Ti
       return (count == 0) ? 0 : result / count;
     }
 
+  /**
+   * @method remove_greater
+   * @brief  Removes from the range [first,last) the elements with a mark greater
+   *         than mark and returns an iterator to the new end of the range,
+   *         which now includes only elements with a mark less than mark.
+   * @param  first  forward iterator to the initial positions in a sequence
+   * @param  last   forward iterator to the final positions in a sequence
+   * @param  mark   maximal value for mark to keep
+   * @return A forward iterator pointing to the new end of the sequence,
+   *         which now includes all the elements with a mark less than mark.
+   * @globalvars none
+   * @exception  none
+   * @pre  All objects in the sequence must have a method mark returning a type
+   *       convertible to double.
+   * @post This function does not alter the elements past the new end,
+   *       which keep their old values and are still accessible.
+   */
   template <class ForwardIterator>
     ForwardIterator remove_greater (ForwardIterator first, ForwardIterator last, int mark)
     {
@@ -55,7 +103,6 @@ namespace Ti
       }
       return result;
     }
-
 }
 
 #endif
diff --git a/ue5/shared_ptr.hpp b/ue5/shared_ptr.hpp
index 37989e3..7f502bd 100644
--- a/ue5/shared_ptr.hpp
+++ b/ue5/shared_ptr.hpp
@@ -1,3 +1,10 @@
+/**
+ * @module shared_ptr
+ * @author Guenther Neuwirth (0626638), Manuel Mausz (0728348)
+ * @brief  Class template shared_ptr
+ * @date   13.06.2009
+ */
+
 #ifndef SHARED_PTR_H
 #define SHARED_PTR_H
 
@@ -8,29 +15,85 @@
 
 namespace Ti
 {
+  /**
+   * @class shared_ptr
+   *
+   * The templates stores a pointer, usually obtained via new.
+   * shared_ptr implements semantics of shared ownership; the last remaining
+   * owner of the pointer is responsible for destroying the object, or
+   * otherwise releasing the resources associated with the stored pointer.
+   * A shared_ptr object is empty if it does not own a pointer.
+   */
   template <typename T>
     class shared_ptr
     {
       private:
+        /** stored pointer */
         T* m_ptr;
+        /** reference counter */
         unsigned long* m_count;
 
       public:
+        /**
+         * @method shared_ptr
+         * @brief  Default ctor
+         * @param  -
+         * @return -
+         * @globalvars none
+         * @exception  none
+         * @pre  none
+         * @post get() == m_count == NULL
+         */
         shared_ptr()
           : m_ptr(NULL), m_count(NULL)
         {}
 
+        /**
+         * @method get
+         * @brief  Returns pointer of enclosed object
+         * @param  -
+         * @return returns the stored pointer, null pointer if *this is empty.
+         * @globalvars none
+         * @exception  none
+         * @pre  none
+         * @post none
+         */
         T* get() const
         {
           return m_ptr;
         }
 
+        /**
+         * @method shared_ptr
+         * @brief  Copy ctor.  If r is empty, constructs an empty shared_ptr
+         *         object - otherwise, constructs a shared_ptr object that
+         *         shares ownership with r.
+         * @param  other  instance to copy from
+         * @return -
+         * @globalvars none
+         * @exception  none
+         * @pre  none
+         * @post get() == other.get() && m_count == other.m_count
+         */
         shared_ptr(const shared_ptr<T>& other)
           : m_ptr(other.m_ptr), m_count(other.m_count)
         {
           add_ref();
         }
 
+        /**
+         * @method shared_ptr
+         * @brief  Copy ctor. If other is empty, constructs an empty shared_ptr
+         *         object - otherwise, constructs a shared_ptr object that
+         *         shares ownership with other.
+         * @param  other  instance to copy from
+         * @return -
+         * @globalvars none
+         * @exception  none
+         * @pre  The constructor shall not participate in the overload
+         *       resolution unless O* is implicitly convertible to T*.
+         * @post get() == other.get() && m_count == other.m_count
+         */
         template <typename O>
           shared_ptr(const shared_ptr<O>& other)
             : m_ptr(other.m_ptr), m_count(other.m_count)
@@ -38,7 +101,18 @@ namespace Ti
             add_ref();
           }
 
-        /* used to construct shared_ptr with a sub-object of O */
+        /**
+         * @method shared_ptr
+         * @brief  Copy ctor. Constructs a shared_ptr instance that stores ptr
+         *         and shares ownership with other.
+         * @param  other  instance to copy from
+         * @param  ptr    ptr to store
+         * @return -
+         * @globalvars none
+         * @exception  none
+         * @pre  none
+         * @post get() == p && m_count == other.m_count
+         */
         template <typename O>
           shared_ptr(const shared_ptr<O>& other, T* ptr)
             : m_ptr(ptr), m_count(other.m_count)
@@ -46,11 +120,33 @@ namespace Ti
             add_ref();
           }
 
+        /**
+         * @method shared_ptr
+         * @brief  Copy ctor. Constructs a shared_ptr object that owns the pointer p.
+         * @param  p  pointer to store
+         * @return -
+         * @globalvars none
+         * @exception  bad_alloc if memory couldn't be optained
+         * @pre  p shall be convertible to T*. Y shall be a complete type. The
+         *       expression delete p shall be well formed, shall have well
+         *       defined behavior, and shall not throw exceptions.
+         * @post get() == p && m_count == 1
+         */
         template <typename O>
           explicit shared_ptr(O* p)
           : m_ptr(p), m_count(new unsigned long(1))
           {}
 
+        /**
+         * @method operator=
+         * @brief  operator =
+         * @param  other  object to compare with
+         * @return always *this
+         * @globalvars none
+         * @exception  none
+         * @pre  none
+         * @post none
+         */
         shared_ptr& operator=(const shared_ptr<T>& other)
         {
           if (*this == other)
@@ -62,6 +158,16 @@ namespace Ti
           return *this;
         }
 
+        /**
+         * @method operator=
+         * @brief  operator =
+         * @param  other  object to compare with
+         * @return always *this
+         * @globalvars none
+         * @exception  none
+         * @pre  none
+         * @post none
+         */
         template <typename O>
           shared_ptr& operator=(const shared_ptr<O>& other)
         {
@@ -74,39 +180,110 @@ namespace Ti
           return *this;
         }
 
+        /**
+         * @method ~shared_ptr
+         * @brief  Dtor
+         * @param  -
+         * @return -
+         * @globalvars none
+         * @exception  none
+         * @pre  none
+         * @post none
+         */
         ~shared_ptr()
         {
           release();
         }
 
+        /**
+         * @method operator*
+         * @brief  operator *
+         * @param  -
+         * @return returns *get()
+         * @globalvars none
+         * @exception  none
+         * @pre  get() != NULL
+         * @post none
+         */
         T& operator*() const
         {
           return *m_ptr;
         }
 
+        /**
+         * @method operator->
+         * @brief  operator ->
+         * @param  -
+         * @return returns get()
+         * @globalvars none
+         * @exception  none
+         * @pre  get() != NULL
+         * @post none
+         */
         T* operator->() const
         {
           return m_ptr;
         }
 
+        /**
+         * @method swap
+         * @brief  Exchanges the contents of *this and other.
+         * @param  other  instance to swap with
+         * @return -
+         * @globalvars none
+         * @exception  none
+         * @pre  none
+         * @post none
+         */
         void swap(shared_ptr<T>& other)
         {
           std::swap(m_ptr, other.m_ptr);
           std::swap(m_count, other.m_count);
         }
 
+        /**
+         * @method reset
+         * @brief  Equivalent to shared_ptr().swap(*this).
+         * @param  -
+         * @return -
+         * @globalvars none
+         * @exception  none
+         * @pre  none
+         * @post none
+         */
         inline void reset()
         {
           shared_ptr().swap(*this);
         }
 
       private:
+        /**
+         * @method add_ref
+         * @brief  Increase reference counter
+         * @param  -
+         * @return -
+         * @globalvars none
+         * @exception  none
+         * @pre  m_count != NULL
+         * @post none
+         */
         void add_ref()
         {
           if (m_count != NULL)
             ++(*m_count);
         }
 
+        /**
+         * @method release
+         * @brief  Decrease reference counter
+         *         if m_count == 0 free all resources
+         * @param  -
+         * @return -
+         * @globalvars none
+         * @exception  none
+         * @pre  m_ptr != NULL && m_count != NULL
+         * @post none
+         */
         void release()
         {
           if (m_ptr != NULL)
@@ -147,48 +324,139 @@ namespace Ti
           friend shared_ptr<R> shared_dynamic_cast(const shared_ptr<F>& from);
     };
 
+  /**
+   * @method make_shared
+   * @brief  Creates an instance of shared_ptr containing a pointer to the
+   *         also created instance of T(args...).
+   * @param  args  arguments for ctor of T.
+   * @return A shared_ptr instance that stores and owns the address of the
+   *         newly constructed object of type T.
+   * @globalvars none
+   * @exception  bad_alloc
+   * @pre  none
+   * @post get() != 0 && use_count() == 1
+   */
   template <typename T, typename ... Args>
     shared_ptr<T> make_shared(Args ... args)
     {
       return shared_ptr<T>(new T(args ...));
     }
 
+  /**
+   * @method operator==
+   * @brief  operator ==
+   * @param  a  object1 to compare
+   * @param  b  object2 to compare
+   * @return true if both objects contain the same pointer, false otherwise.
+   * @globalvars none
+   * @exception  none
+   * @pre  none
+   * @post none
+   */
   template<typename U1, typename U2>
     bool operator==(const shared_ptr<U1>& a, const shared_ptr<U2>& b)
     {
       return a.get() == b.get();
     }
 
+  /**
+   * @method operator==
+   * @brief  operator ==
+   * @param  a  shared_ptr to compare
+   * @param  b  pointer to compare
+   * @return true if a contains pointer b, false otherwise.
+   * @globalvars none
+   * @exception  none
+   * @pre  none
+   * @post none
+   */
   template<typename U1, typename U2>
     bool operator==(const shared_ptr<U1>& a, const U2* b)
     {
       return a.get() == b;
     }
 
+  /**
+   * @method operator==
+   * @brief  operator ==
+   * @param  a  pointer to compare
+   * @param  b  shared_ptr to compare
+   * @return true if b contains pointer a, false otherwise.
+   * @globalvars none
+   * @exception  none
+   * @pre  none
+   * @post none
+   */
   template<typename U1, typename U2>
     bool operator==(const U1* a, const shared_ptr<U2>& b)
     {
       return a == b.get();
     }
 
+  /**
+   * @method operator!=
+   * @brief  operator !=
+   * @param  a  shared_ptr to compare
+   * @param  b  pointer to compare
+   * @return true if a contains different pointer than b, false otherwise.
+   * @globalvars none
+   * @exception  none
+   * @pre  none
+   * @post none
+   */
   template<typename U1, typename U2>
     bool operator!=(const shared_ptr<U1>& a, const U2* b)
     {
       return a.get() != b;
     }
 
+  /**
+   * @method operator!=
+   * @brief  operator !=
+   * @param  a  pointer to compare
+   * @param  b  shared_ptr to compare
+   * @return true if b contains different pointer than a, false otherwise.
+   * @globalvars none
+   * @exception  none
+   * @pre  none
+   * @post none
+   */
   template<typename U1, typename U2>
     bool operator!=(const U1* a, const shared_ptr<U2>& b)
     {
       return a != b.get();
     }
 
+  /**
+   * @method operator!=
+   * @brief  operator !=
+   * @param  a  object1 to compare
+   * @param  b  object2 to compare
+   * @return true if both objects contain different pointers, false otherwise.
+   * @globalvars none
+   * @exception  none
+   * @pre  none
+   * @post none
+   */
   template<typename U1, typename U2>
     bool operator!=(const shared_ptr<U1>& a, const shared_ptr<U2>& b)
     {
       return a.get() != b.get();
     }
 
+  /**
+   * @method shared_dynamic_cast
+   * @brief  Converts pointer from F to T by using dynamic_cast.
+   * @param  from  object to cast
+   * @return When dynamic_cast<T*>(from.get()) returns a nonzero value,
+   *         a shared_ptr<T> object that stores a copy of it and shares
+   *         ownership with from - otherwise an empty shared_ptr<T> object.
+   * @globalvars none
+   * @exception  none
+   * @pre  The expression shared_dynamic_cast<T*>(from.get()) shall be well
+   *       formed and shall have well defined behavior.
+   * @post w.get() == dynamic_cast<T*>(from.get()), where w is the return value.
+   */
   template <typename T, typename F>
     shared_ptr<T> shared_dynamic_cast(const shared_ptr<F>& from)
     {
@@ -203,6 +471,18 @@ namespace Ti
 namespace std
 {
   using namespace Ti;
+
+  /**
+   * @method swap
+   * @brief  Exchanges the contents of t1 and t2.
+   * @param  t1  instance#1 of shared_ptr
+   * @param  t2  instance#2 of shared_ptr
+   * @return -
+   * @globalvars none
+   * @exception  none
+   * @pre  none
+   * @post none
+   */
   template <typename T>
     inline void swap(shared_ptr<T>& t1, shared_ptr<T>& t2)
     {