Improve comments related to vector transients

arximboldi · Jan 18, 2017 · 041a45c · 041a45c
1 parent 162946c
commit 041a45c
Show file tree

Hide file tree

Showing 4 changed files with 31 additions and 6 deletions.
diff --git a/immer/flex_vector.hpp b/immer/flex_vector.hpp
@@ -251,7 +251,8 @@ class flex_vector
     { return l.impl_.concat(r.impl_); }
 
     /*!
-     * Returns a `transient` form of this container.
+     * Returns an @a transient form of this container, an
+     * `immer::flex_vector_transient`.
      */
     transient_type transient() const&
     { return transient_type{ impl_ }; }

diff --git a/immer/flex_vector_transient.hpp b/immer/flex_vector_transient.hpp
@@ -38,6 +38,16 @@ template <typename T,
           detail::rbts::bits_t BL>
 class vector_transient;
 
+/*!
+ * Mutable version of `immer::flex_vector`.
+ *
+ * @rst
+ *
+ * Refer to :doc:`transients` to learn more about when and how to use
+ * the mutable versions of immutable containers.
+ *
+ * @endrst
+ */
 template <typename T,
           typename MemoryPolicy   = default_memory_policy,
           detail::rbts::bits_t B  = default_bits,
@@ -173,7 +183,8 @@ class flex_vector_transient
     { impl_.drop_mut(*this, elems); }
 
     /*!
-     * Returns a `persistent` form of this container.
+     * Returns an @a immutable form of this container, an
+     * `immer::flex_vector`.
      */
     persistent_type persistent() const&
     { return persistent_type{ impl_ }; }

diff --git a/immer/vector.hpp b/immer/vector.hpp
@@ -226,7 +226,8 @@ class vector
     { impl_.for_each_chunk(std::forward<Fn>(fn)); }
 
     /*!
-     * Returns a `transient` form of this container.
+     * Returns an @a transient form of this container, an
+     * `immer::vector_transient`.
      */
     transient_type transient() const&
     { return transient_type{ impl_ }; }

diff --git a/immer/vector_transient.hpp b/immer/vector_transient.hpp
@@ -38,6 +38,16 @@ template <typename T,
           detail::rbts::bits_t BL>
 class flex_vector_transient;
 
+/*!
+ * Mutable version of `immer::vector`.
+ *
+ * @rst
+ *
+ * Refer to :doc:`transients` to learn more about when and how to use
+ * the mutable versions of immutable containers.
+ *
+ * @endrst
+ */
 template <typename T,
           typename MemoryPolicy   = default_memory_policy,
           detail::rbts::bits_t B  = default_bits,
@@ -66,8 +76,9 @@ class vector_transient
     using persistent_type  = vector<T, MemoryPolicy, B, BL>;
 
     /*!
-     * Default constructor.  It creates a vector of `size() == 0`.  It
-     * does not allocate memory and its complexity is @f$ O(1) @f$.
+     * Default constructor.  It creates a mutable vector of `size() ==
+     * 0`.  It does not allocate memory and its complexity is
+     * @f$ O(1) @f$.
      */
     vector_transient() = default;
 
@@ -154,7 +165,8 @@ class vector_transient
     { impl_.take_mut(*this, elems); }
 
     /*!
-     * Returns a `persistent` form of this container.
+     * Returns an @a immutable form of this container, an
+     * `immer::vector`.
      */
     persistent_type persistent() const&
     { return persistent_type{ impl_ }; }