Documentation, better conformance to AttributeChecker conventions

Both PairChecker and AttributeContainerChecker factory functions modified to return more generic AttributeCheckers similar to other attribute types. By removing the templated return type, the internal templated classes become necessary to define checkers for each templated type. This follows the pattern in PointerChecker and ObjectContainerChecker. The pair-value-test-suite and attribute-container-test-suite were amended to account for the changes in the checker factories. All tests continue to pass. Plenty of documentation was added to PairValue and AttributeContainerValue and I also removed some dead code.
2020-09-10 16:43:51 -06:00
parent c8f2bf250e
commit d244597a2b
6 changed files with 226 additions and 55 deletions
--- a/src/core/model/attribute-container.h
+++ b/src/core/model/attribute-container.h
@@ -21,7 +21,7 @@
 #ifndef ATTRIBUTE_CONTAINER_H
 #define ATTRIBUTE_CONTAINER_H

-#include <ns3/ptr.h>
+#include <ns3/attribute-helper.h>
 #include <ns3/string.h>

 #include <list>
@@ -37,62 +37,151 @@ namespace ns3 {
 class AttributeChecker;

 // A = attribute value type, C = container type to return
+/**
+ * A container for one type of attribute.
+ * 
+ * The container uses \ref A to parse items into elements.
+ * Internally the container is always a list but an instance
+ * can return the items in a container specified by \ref C.
+ * 
+ * @tparam A AttributeValue type to be contained.
+ * @tparam C Possibly templated container class returned by Get.
+ */
 template <class A, template<class...> class C=std::list>
 class AttributeContainerValue : public AttributeValue
 {
 public:
+  /** AttributeValue (element) type. */
  typedef A attribute_type;
+  /** Type actually stored within the container. */
  typedef Ptr<A> value_type;
+  /** Internal container type. */
  typedef std::list<value_type> container_type;
+  /** stl-style Const iterator type. */
  typedef typename container_type::const_iterator const_iterator;
+  /** stl-style Non-const iterator type. */
  typedef typename container_type::iterator iterator;
+  /** Size type for container. */
  typedef typename container_type::size_type size_type;
+  /** NS3 style iterator type. */
  typedef typename AttributeContainerValue::const_iterator Iterator; // NS3 type

  // use underlying AttributeValue to get return element type
+  /** Item type of container returned by Get. */
  typedef typename std::result_of<decltype(&A::Get)(A)>::type item_type;
+  /** Type of container returned. */
  typedef C<item_type> result_type;

+  /**
+   * Default constructor.
+   * \param[in] sep Character separator between elements for parsing.
+   */
  AttributeContainerValue (char sep = ',');

+  /**
+   * Construct from another container.
+   * @tparam CONTAINER[deduced] type of container passed for initialization.
+   * \param c Instance of CONTAINER with which to initialize AttributeContainerValue.
+   */
  template <class CONTAINER>
  AttributeContainerValue (const CONTAINER &c);

+  /**
+   * Construct from iterators.
+   * @tparam ITER[deduced] type of iterator.
+   * \param[in] begin Iterator that points to first initialization item.
+   * \param[in] end Iterator that points ones past last initialization item.
+   */
  template <class ITER>
  AttributeContainerValue (const ITER begin, const ITER end);

+  /** Destructor. */
  ~AttributeContainerValue ();

+  // Inherited
  Ptr<AttributeValue> Copy (void) const;
-
-  bool DeserializeFromString (std::string value, Ptr<const AttributeChecker > checker);
+  bool DeserializeFromString (std::string value, Ptr<const AttributeChecker> checker);
  std::string SerializeToString (Ptr<const AttributeChecker> checker) const;

  // defacto pure virtuals to integrate with built-in accessor code
+  /**
+   * Return a container of items.
+   * \return Container of items.
+   */
  result_type Get (void) const;
+  /**
+   * Copy items from container c.
+   * 
+   * This method assumes \ref c has stl-style begin and end methods.
+   * The AttributeContainerValue value is cleared before copying from \ref c.
+   * @tparam T type of container.
+   * \param c Container from which to copy items.
+   */
  template <class T>
  void Set (const T &c);

  // NS3 interface
+  /**
+   * NS3-style Number of items.
+   * \return Number of items in container.
+   */
  size_type GetN (void) const;
+  /**
+   * NS3-style beginning of container.
+   * \return Iterator pointing to first time in container.
+   */
  Iterator Begin (void);
+  /**
+   * NS3-style ending of container.
+   * \return Iterator pointing one past last item of container.
+   */
  Iterator End (void);

+  // STL-interface
+  /**
+   * STL-style number of items in container
+   * \return number of items in container.
+   */
  size_type size (void) const;
+  /**
+   * STL-style beginning of container.
+   * \return Iterator pointing to first item in container.
+   */
  iterator begin (void);
+  /**
+   * STL-style end of container.
+   * \return Iterator pointing to one past last item in container.
+   */
  iterator end (void);
+  /**
+   * STL-style const beginning of container.
+   * \return Const iterator pointing to first item in container.
+   */
  const_iterator begin (void) const;
+  /**
+   * STL-style const end of container.
+   * \return Const iterator pointing to one past last item in container.
+   */
  const_iterator end (void) const;

 private:
+  /**
+   * Copy items from \ref begin to \ref end. 
+   * 
+   * The internal container is cleared before values are copied
+   * using the push_back method.
+   * @tparam ITER[deduced] iterator type
+   * \param[in] begin Points to first item to copy
+   * \param[in] end Points to one after last item to copy
+   * \return This object with items copied.
+   */
  template <class ITER>
  Ptr<AttributeContainerValue<A, C> > CopyFrom (const ITER begin, const ITER end);

-  char m_sep;
-  container_type m_container;
+  char m_sep;                 //!< Item separator
+  container_type m_container; //!< Internal container
 };

-template <class A, template <class...> class C>
 class AttributeContainerChecker : public AttributeChecker
 {
 public:
@@ -101,22 +190,35 @@ public:
 };

 /**
- * Return checker using attribute value to provide types
+ * Make AttributeContainerChecker from AttributeContainerValue.
+ * @tparam A[deduced] AttributeValue type in container.
+ * @tparam C[deduced] Container type returned by Get.
+ * \param value[in] AttributeContainerValue from which to deduce types.
+ * \return AttributeContainerChecker for \ref value.
 */
 template <class A, template <class...> class C>
-Ptr<AttributeContainerChecker<A, C> >
+Ptr<AttributeChecker>
 MakeAttributeContainerChecker (const AttributeContainerValue<A, C> &value);

 /**
- * Return checker give types explicitly, defaults same
- * as AttributeContainerValue defaults
+ * Make AttributeContainerChecker using explicit types, initialize item checker.
+ * @tparam A AttributeValue type in container.
+ * @tparam C Container type returned by Get.
+ * \param itemchecker[in] AttributeChecker used for each item in the container.
+ * \return AttributeContainerChecker.
 */
 template <class A, template <class...> class C=std::list>
-Ptr<AttributeContainerChecker<A, C> >
+Ptr<const AttributeChecker>
 MakeAttributeContainerChecker (Ptr<const AttributeChecker> itemchecker);

+/**
+ * Make unitialized AttributeContainerChecker using explicit types.
+ * @tparam A AttributeValue type in container.
+ * @tparam C Container type returned by Get.
+ * \return AttributeContainerChecker.
+ */
 template <class A, template <class...> class C=std::list>
-Ptr<AttributeContainerChecker<A, C> > MakeAttributeContainerChecker (void);
+Ptr<AttributeChecker> MakeAttributeContainerChecker (void);

 template <typename A, template <typename...> class C=std::list, typename T1>
 Ptr<const AttributeAccessor> MakeAttributeContainerAccessor (T1 a1);
@@ -129,10 +231,14 @@ Ptr<const AttributeAccessor> MakeAttributeContainerAccessor (T1 a1);

 namespace ns3 {

+// This internal class defines templated AttributeContainerChecker class that is instantiated
+// in MakeAttributeContainerChecker. The non-templated base ns3::AttributeContainerChecker
+// is returned from that function. This is the same pattern as ObjectPtrContainer.
+
 namespace internal {

 template <class A, template <class...> class C>
-class AttributeContainerChecker : public ns3::AttributeContainerChecker<A, C>
+class AttributeContainerChecker : public ns3::AttributeContainerChecker
 {
 public:
  AttributeContainerChecker (void);
@@ -171,32 +277,34 @@ AttributeContainerChecker<A, C>::GetItemChecker (void) const
 } // namespace internal

 template <class A, template <class...> class C>
-Ptr<AttributeContainerChecker<A, C> >
+Ptr<AttributeChecker>
 MakeAttributeContainerChecker (const AttributeContainerValue<A, C> &value)
 {
  return MakeAttributeContainerChecker <A, C> ();
 }

 template <class A, template <class...> class C>
-Ptr<AttributeContainerChecker<A, C> >
+Ptr<const AttributeChecker>
 MakeAttributeContainerChecker (Ptr<const AttributeChecker> itemchecker)
 {
  auto checker = MakeAttributeContainerChecker <A, C> ();
-  checker->SetItemChecker (itemchecker);
+  auto acchecker = DynamicCast<AttributeContainerChecker> (checker);
+  acchecker->SetItemChecker (itemchecker);
  return checker;
 }

 template <class A, template <class...> class C>
-Ptr<AttributeContainerChecker<A, C> >
+Ptr<AttributeChecker>
 MakeAttributeContainerChecker (void)
 {
-  std::string typeName, underlyingType;
+  std::string containerType;
+  std::string underlyingType;
  typedef AttributeContainerValue<A, C> T;
  {
    std::ostringstream oss;
    oss << "ns3::AttributeContainerValue<" << typeid (typename T::attribute_type).name ()
        << ", " << typeid (typename T::container_type).name () << ">";
-    typeName = oss.str ();
+    containerType = oss.str ();
  }

  {
@@ -205,9 +313,7 @@ MakeAttributeContainerChecker (void)
    underlyingType = oss.str ();
  }

-  return DynamicCast<AttributeContainerChecker<A, C> > (
-    MakeSimpleAttributeChecker<T, internal::AttributeContainerChecker<A, C> > (typeName, underlyingType)
-  );
+  return MakeSimpleAttributeChecker<T, internal::AttributeContainerChecker<A, C> > (containerType, underlyingType);
 }

 template <class A, template <class...> class C>
@@ -253,7 +359,7 @@ template <class A, template <class...> class C>
 bool
 AttributeContainerValue<A, C>::DeserializeFromString (std::string value, Ptr<const AttributeChecker> checker)
 {
-  auto acchecker = DynamicCast<const AttributeContainerChecker<A, C> > (checker);
+  auto acchecker = DynamicCast<const AttributeContainerChecker> (checker);
  if (!acchecker) return false;

  std::istringstream iss (value); // copies value
--- a/src/core/model/pair.h
+++ b/src/core/model/pair.h
@@ -21,8 +21,7 @@
 #ifndef PAIR_H
 #define PAIR_H

-#include <ns3/attribute.h>
-#include <ns3/ptr.h>
+#include <ns3/attribute-helper.h>
 #include <ns3/string.h>

 #include <sstream>
@@ -32,9 +31,6 @@

 namespace ns3 {

-class AttributeChecker;
-
-// TODO: useful to maybe define some kind of configurable formatter?
 template <class A, class B>
 std::ostream &
 operator << (std::ostream &os, const std::pair<A, B> &p)
@@ -43,26 +39,49 @@ operator << (std::ostream &os, const std::pair<A, B> &p)
  return os;
 }

-// A = attribute value type, C = container type to return
+// Doxygen for this class is auto-generated by
+// utils/print-introspected-doxygen.h
+
+/** Hold objects of type std::pair<A, B>. */
 template <class A, class B>
 class PairValue : public AttributeValue
 {
 public:
+  /** Type of value stored in the PairValue. */
  typedef std::pair<Ptr<A>, Ptr<B> > value_type;
+  /** Type of abscissa (first entry of pair). */
  typedef typename std::result_of<decltype(&A::Get)(A)>::type first_type;
+  /** Type of ordinal (second entry of pair). */
  typedef typename std::result_of<decltype(&B::Get)(B)>::type second_type;
+  /** Type returned by Get or passed in Set. */
  typedef typename std::pair<first_type, second_type> result_type;
-  typedef typename std::pair<const first_type, second_type> map_value_type;

  PairValue ();
+  
+  /**
+   * Construct this PairValue from a std::pair
+   *
+   * \param [in] value Value with which to construct.
+   */
  PairValue (const result_type &value); // "import" constructor

+  // Inherited
  Ptr<AttributeValue> Copy (void) const;
-
  bool DeserializeFromString (std::string value, Ptr<const AttributeChecker> checker);
  std::string SerializeToString (Ptr<const AttributeChecker> checker) const;

+  /**
+   * Get the stored value as a std::pair.
+   * 
+   * This differs from the actual value stored in the object which is 
+   * a pair of Ptr<AV> where AV is a class derived from AttributeValue.
+   * \return stored value as std::pair<A, B>.
+   */
  result_type Get (void) const;
+  /**
+   * Set the stored value.
+   * \param[in] value std::pair<A, B> to be stored.
+   */
  void Set (const result_type &value);

  template <typename T>
@@ -72,26 +91,60 @@ private:
  value_type m_value;
 };

-template <class A, class B>
 class PairChecker : public AttributeChecker
 {
 public:
  typedef std::pair<Ptr<const AttributeChecker>, Ptr<const AttributeChecker> > checker_pair_type;

+  /**
+   * Set the individual AttributeChecker for each pair entry.
+   * 
+   * \param[in] firstchecker AttributeChecker for abscissa.
+   * \param[in] secondchecker AttributeChecker for ordinate.
+   */
  virtual void SetCheckers (Ptr<const AttributeChecker> firstchecker, Ptr<const AttributeChecker> secondchecker) = 0;
+  
+  /**
+   * Get the pair of checkers for each pair entry.
+   * 
+   * \return std::pair with AttributeChecker for each of abscissa and ordinate.
+   */
  virtual checker_pair_type GetCheckers (void) const = 0;
 };

+/**
+ * Make a PairChecker from a PairValue.
+ * 
+ * This function returns a Pointer to a non-const instance to
+ * allow subsequent setting of the underlying AttributeCheckers.
+ * \param[in] value PairValue from which to derive abscissa and ordinate types.
+ * \return Pointer to PairChecker instance.
+ */
 template <class A, class B>
-Ptr<PairChecker<A, B> >
+Ptr<AttributeChecker>
 MakePairChecker (const PairValue<A, B> &value);

+/**
+ * Make a PairChecker from abscissa and ordinate AttributeCheckers.
+ * 
+ * This function returns a Pointer to a const instance since both
+ * underlying AttributeCheckers are set.
+ * 
+ * \param[in] firstchecker AttributeChecker for abscissa.
+ * \param[in] secondchecker AttributeChecker for ordinate.
+ * \return Pointer to PairChecker instance.
+ */
 template <class A, class B>
-Ptr<PairChecker<A, B> >
+Ptr<const AttributeChecker>
 MakePairChecker (Ptr<const AttributeChecker> firstchecker, Ptr<const AttributeChecker> secondchecker);

+/**
+ * Make a PairChecker without abscissa and ordinate AttributeCheckers.
+ * 
+ * \return Pointer to PairChecker instance.
+ */
 template <class A, class B>
-Ptr<PairChecker<A, B> > MakePairChecker (void);
+Ptr<AttributeChecker> MakePairChecker (void);

 template <typename A, typename B, typename T1>
 Ptr<const AttributeAccessor> MakePairAccessor (T1 a1);
@@ -104,16 +157,23 @@ Ptr<const AttributeAccessor> MakePairAccessor (T1 a1);

 namespace ns3 {

+// This internal class defines templated PairChecker class that is instantiated
+// in MakePairChecker. The non-templated base ns3::PairChecker is returned in that
+// function. This is the same pattern as ObjectPtrContainer.
 namespace internal {

+/**
+ * Internal checker class templated to each AttributeChecker
+ * for each entry in the pair.
+ */
 template <class A, class B>
-class PairChecker : public ns3::PairChecker<A, B>
+class PairChecker : public ns3::PairChecker
 {
 public:
  PairChecker (void);
  PairChecker (Ptr<const AttributeChecker> firstchecker, Ptr<const AttributeChecker> secondchecker);
  void SetCheckers (Ptr<const AttributeChecker> firstchecker, Ptr<const AttributeChecker> secondchecker);
-  typename ns3::PairChecker<A, B>::checker_pair_type GetCheckers (void) const;
+  typename ns3::PairChecker::checker_pair_type GetCheckers (void) const;

 private:
  Ptr<const AttributeChecker> m_firstchecker;
@@ -141,7 +201,7 @@ PairChecker<A, B>::SetCheckers (Ptr<const AttributeChecker> firstchecker, Ptr<co
 }

 template <class A, class B>
-typename ns3::PairChecker<A, B>::checker_pair_type
+typename ns3::PairChecker::checker_pair_type
 PairChecker<A, B>::GetCheckers (void) const
 {
  return std::make_pair (m_firstchecker, m_secondchecker);
@@ -150,26 +210,28 @@ PairChecker<A, B>::GetCheckers (void) const
 } // namespace internal

 template <class A, class B>
-Ptr<PairChecker<A, B> >
+Ptr<AttributeChecker>
 MakePairChecker (const PairValue<A, B> &value)
 {
  return MakePairChecker <A, B> ();
 }

 template <class A, class B>
-Ptr<PairChecker<A, B> >
+Ptr<const AttributeChecker>
 MakePairChecker (Ptr<const AttributeChecker> firstchecker, Ptr<const AttributeChecker> secondchecker)
 {
  auto checker = MakePairChecker <A, B> ();
-  checker->SetCheckers (firstchecker, secondchecker);
+  auto acchecker = DynamicCast<PairChecker> (checker);
+  acchecker->SetCheckers (firstchecker, secondchecker);
  return checker;
 }

 template <class A, class B>
-Ptr<PairChecker<A, B> >
+Ptr<AttributeChecker>
 MakePairChecker (void)
 {
-  std::string pairName, underlyingType;
+  std::string pairName;
+  std::string underlyingType;
  typedef PairValue<A, B> T;
  std::string first_type_name = typeid (typename T::value_type::first_type).name ();
  std::string second_type_name = typeid (typename T::value_type::second_type).name ();
@@ -185,9 +247,7 @@ MakePairChecker (void)
    underlyingType = oss.str ();
  }

-  return DynamicCast<PairChecker<A, B> > (
-    MakeSimpleAttributeChecker<T, internal::PairChecker<A, B> > (pairName, underlyingType)
-    );
+  return MakeSimpleAttributeChecker<T, internal::PairChecker<A, B> > (pairName, underlyingType);
 }

 template <class A, class B>
@@ -217,7 +277,7 @@ template <class A, class B>
 bool
 PairValue<A, B>::DeserializeFromString (std::string value, Ptr<const AttributeChecker> checker)
 {
-  auto pchecker = DynamicCast<const PairChecker<A, B> > (checker);
+  auto pchecker = DynamicCast<const PairChecker> (checker);
  if (!pchecker) return false;

  std::istringstream iss (value);  // copies value
--- a/src/core/test/attribute-container-test-suite.cc
+++ b/src/core/test/attribute-container-test-suite.cc
@@ -258,8 +258,8 @@ AttributeContainerSerializationTestCase::DoRun (void)

    AttributeContainerValue<DoubleValue> attr;
    auto checker = MakeAttributeContainerChecker (attr);
-    //auto acchecker = DynamicCast<AttributeContainerChecker <DoubleValue, std::list> > (checker);
-    checker->SetItemChecker (MakeDoubleChecker<double> ());
+    auto acchecker = DynamicCast<AttributeContainerChecker> (checker);
+    acchecker->SetItemChecker (MakeDoubleChecker<double> ());
    NS_TEST_ASSERT_MSG_EQ (attr.DeserializeFromString (doubles, checker), true, "Deserialize failed");
    NS_TEST_ASSERT_MSG_EQ (attr.GetN (), 3, "Incorrect container size");

@@ -275,7 +275,8 @@ AttributeContainerSerializationTestCase::DoRun (void)

    AttributeContainerValue<IntegerValue> attr;
    auto checker = MakeAttributeContainerChecker (attr);
-    checker->SetItemChecker (MakeIntegerChecker<int> ());
+    auto acchecker = DynamicCast<AttributeContainerChecker> (checker);
+    acchecker->SetItemChecker (MakeIntegerChecker<int> ());
    NS_TEST_ASSERT_MSG_EQ (attr.DeserializeFromString (ints, checker), true, "Deserialize failed");
    NS_TEST_ASSERT_MSG_EQ (attr.GetN (), 4, "Incorrect container size");

@@ -290,7 +291,8 @@ AttributeContainerSerializationTestCase::DoRun (void)

    AttributeContainerValue<StringValue> attr (' ');
    auto checker = MakeAttributeContainerChecker (attr);
-    checker->SetItemChecker (MakeStringChecker ());
+    auto acchecker = DynamicCast<AttributeContainerChecker> (checker);
+    acchecker->SetItemChecker (MakeStringChecker ());
    NS_TEST_ASSERT_MSG_EQ (attr.DeserializeFromString (strings, checker), true, "Deserialize failed");
    NS_TEST_ASSERT_MSG_EQ (attr.GetN (), 6, "Incorrect container size");

@@ -303,7 +305,8 @@ AttributeContainerSerializationTestCase::DoRun (void)
    std::string pairs = "one 1,two 2,three 3";
    AttributeContainerValue<PairValue<StringValue, IntegerValue> > attr;
    auto checker = MakeAttributeContainerChecker (attr);
-    checker->SetItemChecker (MakePairChecker <StringValue, IntegerValue> (
+    auto acchecker = DynamicCast<AttributeContainerChecker> (checker);
+    acchecker->SetItemChecker (MakePairChecker <StringValue, IntegerValue> (
                                MakeStringChecker (), MakeIntegerChecker<int> ()));
    NS_TEST_ASSERT_MSG_EQ (attr.DeserializeFromString (pairs, checker), true, "Deserialization failed");
    NS_TEST_ASSERT_MSG_EQ (attr.GetN (), 3, "Incorrect container size");
--- a/src/core/test/pair-value-test-suite.cc
+++ b/src/core/test/pair-value-test-suite.cc
@@ -155,9 +155,10 @@ PairValueSettingsTestCase::DoRun ()
  p->SetAttribute ("StringPair", PairValue<StringValue, StringValue> (std::make_pair ("hello", "world")));
  p->SetAttribute ("AddressPair", PairValue<AddressValue, IntegerValue> (std::make_pair (addr, 31)));

-  std::ostringstream oss, ref;
+  std::ostringstream oss;
  oss << *p;
-
+  
+  std::ostringstream ref;
  ref << "StringPair = { (hello,world) } AddressPair = { (" << addr << ",31) }";

  NS_TEST_ASSERT_MSG_EQ ((oss.str ()), (ref.str ()), "Pairs not correctly set");
--- a/src/core/wscript
+++ b/src/core/wscript
@@ -339,6 +339,7 @@ def build(bld):
        'model/object-factory.h',
        'model/attribute-helper.h',
        'model/attribute-container.h',
+        'model/attribute-container-accessor-helper.h',
        'model/global-value.h',
        'model/traced-callback.h',
        'model/traced-value.h',
--- a/utils/print-introspected-doxygen.cc
+++ b/utils/print-introspected-doxygen.cc
@@ -1572,7 +1572,7 @@ PrintAttributeImplementations (std::ostream & os)
  PrintMakeChecker            (os, "ObjectMap", "object-map.h");

  PrintAttributeValueSection  (os, "Pair", false);
-  PrintAttributeValueWithName (os, "Pair", "Pair", "pair.h");
+  PrintAttributeValueWithName (os, "Pair", "std::pair<A, B>", "pair.h");
  PrintMakeChecker            (os, "Pair",  "pair.h");
  
  PrintAttributeValueSection  (os, "AttributeContainer", false);