libuavcan documentation

libuavcan/include/uavcan/util/lazy_constructor.hpp

@@ -15,7 +15,13 @@
 
 namespace uavcan
 {
-
+/**
+ * This class allows to postpone the object contruction.
+ * It statically allocates a pool of memory of just enough size to fit the object being constructed.
+ * Later call to construct<>() calls the constructor of the object.
+ * The object will be destroyed automatically when the container class destructor is called.
+ * The memory pool is aligned at the size of the largest primitive type (long double or long long int).
+ */
 template <typename T>
 class UAVCAN_EXPORT LazyConstructor
 {

libuavcan/include/uavcan/util/linked_list.hpp

@@ -51,17 +51,27 @@ public:
     T* get() const { return root_; }
     bool isEmpty() const { return get() == NULL; }
 
+    /**
+     * Complexity: O(N)
+     */
     unsigned getLength() const;
 
+    /**
+     * Complexity: O(N) (calls remove())
+     */
     void insert(T* node);
 
     /**
-     * Inserts node A immediately before the node B where
+     * Inserts the node immediately before the node B where
      *  predicate(B) -> true.
+     * Complexity: O(2N) (calls remove())
      */
     template <typename Predicate>
     void insertBefore(T* node, Predicate predicate);
 
+    /**
+     * Complexity: O(N)
+     */
     void remove(const T* node);
 };
 

libuavcan/include/uavcan/util/map.hpp

@@ -15,6 +15,14 @@ namespace uavcan
 {
 /**
  * Slow but memory efficient KV container.
+ *
+ * KV pairs can be allocated in a static buffer or in the node's memory pool if the static buffer is exhausted.
+ * When a KV pair is deleted from the static buffer, one pair from the memory pool will be moved in the free
+ * slot of the static buffer, so the use of the memory pool is minimized.
+ *
+ * Please be aware that this container does not perform any speed optimizations to minimize memory footprint,
+ * so the complexity of most operations is O(N).
+ *
  * Type requirements:
  *  Both key and value must be copyable, assignable and default constructible.
  *  Key must implement a comparison operator.
@@ -124,21 +132,34 @@ protected:
     ~MapBase() { }
 
 public:
+    /**
+     * Returns null pointer if there's no such entry.
+     */
     Value* access(const Key& key);
 
-    /// If entry with the same key already exists, it will be replaced
+    /**
+     * If entry with the same key already exists, it will be replaced
+     */
     Value* insert(const Key& key, const Value& value);
 
+    /**
+     * Does nothing if there's no such entry.
+     */
     void remove(const Key& key);
 
     /**
-     * Remove entries where predicate returns true.
+     * Removes entries where the predicate returns true.
      * Predicate prototype:
      *  bool (const Key& key, const Value& value)
      */
     template <typename Predicate>
     void removeWhere(Predicate predicate);
 
+    /**
+     * Returns first entry where the predicate returns true.
+     * Predicate prototype:
+     *  bool (const Key& key, const Value& value)
+     */
     template <typename Predicate>
     const Key* findFirstKey(Predicate predicate) const;
 

libuavcan/include/uavcan/util/method_binder.hpp

@@ -10,7 +10,11 @@
 
 namespace uavcan
 {
-
+/**
+ * Use this to call member functions as callbacks in C++03 mode.
+ *
+ * In C++11 or newer you don't need it because you can use std::function<>/std::bind<> instead.
+ */
 template <typename ObjectPtr, typename MemFunPtr>
 class UAVCAN_EXPORT MethodBinder
 {
@@ -36,17 +40,26 @@ public:
         , fun_(f)
     { }
 
+    /**
+     * Returns true if the binder is initialized (doesn't contain null pointers).
+     */
     operator bool() const
     {
         return try_implicit_cast<bool>(obj_, true) && try_implicit_cast<bool>(fun_, true);
     }
 
+    /**
+     * Will raise a fatal error if either method pointer or object pointer are null.
+     */
     void operator()()
     {
         validateBeforeCall();
         (obj_->*fun_)();
     }
 
+    /**
+     * Will raise a fatal error if either method pointer or object pointer are null.
+     */
     template <typename Par1>
     void operator()(Par1& p1)
     {
@@ -54,6 +67,9 @@ public:
         (obj_->*fun_)(p1);
     }
 
+    /**
+     * Will raise a fatal error if either method pointer or object pointer are null.
+     */
     template <typename Par1, typename Par2>
     void operator()(Par1& p1, Par2& p2)
     {

libuavcan/include/uavcan/util/placement_new.hpp

@@ -7,6 +7,11 @@
 #include <cstddef>
 #include <uavcan/impl_constants.hpp>
 
+/*
+ * Some embedded C++ implementations don't implement the placement new operator.
+ * Define UAVCAN_IMPLEMENT_PLACEMENT_NEW to apply this workaround.
+ */
+
 #ifndef UAVCAN_IMPLEMENT_PLACEMENT_NEW
 # error UAVCAN_IMPLEMENT_PLACEMENT_NEW
 #endif

libuavcan/include/uavcan/util/templates.hpp

@@ -63,14 +63,18 @@ struct UAVCAN_EXPORT EnableIf<true, T>
     typedef T Type;
 };
 
-
+/**
+ * Lightweight type categorization.
+ */
 template <typename T, typename R = void>
 struct UAVCAN_EXPORT EnableIfType
 {
     typedef R Type;
 };
 
-
+/**
+ * Compile-time type selection (Alexandrescu)
+ */
 template <bool Condition, typename TrueType, typename FalseType>
 struct UAVCAN_EXPORT Select;
 
@@ -111,7 +115,11 @@ public:
     enum { Result = sizeof(True_) == sizeof(IsImplicitlyConvertibleFromTo<T1, T2>::test(returner<T1>())) };
 };
 
-
+/**
+ * try_implicit_cast<>(From)
+ * try_implicit_cast<>(From, To)
+ * @{
+ */
 template <typename From, typename To>
 struct UAVCAN_EXPORT TryImplicitCastImpl
 {
@@ -119,6 +127,10 @@ struct UAVCAN_EXPORT TryImplicitCastImpl
     static To impl(const From&, const To& default_, FalseType) { return default_; }
 };
 
+/**
+ * If possible, performs an implicit cast from the type From to the type To.
+ * If the cast is not possible, returns default_ of type To.
+ */
 template <typename To, typename From>
 UAVCAN_EXPORT
 To try_implicit_cast(const From& from, const To& default_)
@@ -127,6 +139,10 @@ To try_implicit_cast(const From& from, const To& default_)
                                                BooleanType<IsImplicitlyConvertibleFromTo<From, To>::Result>());
 }
 
+/**
+ * If possible, performs an implicit cast from the type From to the type To.
+ * If the cast is not possible, returns a default constructed object of the type To.
+ */
 template <typename To, typename From>
 UAVCAN_EXPORT
 To try_implicit_cast(const From& from)
@@ -134,9 +150,13 @@ To try_implicit_cast(const From& from)
     return TryImplicitCastImpl<From, To>::impl(from, To(),
                                                BooleanType<IsImplicitlyConvertibleFromTo<From, To>::Result>());
 }
+/**
+ * @}
+ */
 
 /**
- * Some arithmetics
+ * Compile time square root for integers.
+ * Useful for operations on square matrices.
  */
 template <unsigned Value> struct UAVCAN_EXPORT CompileTimeIntSqrt;
 template <> struct UAVCAN_EXPORT CompileTimeIntSqrt<4>  { enum { Result = 2 }; };