docs: extend docs for Data View group and its classes

lukaszstolarczuk · lukaszstolarczuk · commit 5b4a0413c0ce · 2021-10-20T14:55:45.000+02:00
diff --git a/doc/groups_definitions.dox b/doc/groups_definitions.dox
@@ -183,7 +183,14 @@
   * @snippet inline_string/inline_string.cpp inline_string_example
   */
 
-/** @defgroup data_view Data View*/
+/** @defgroup data_view Data View
+  * Various views of persistent objects
+  *
+  * Classes listed on this page provide (often simplified) views of persistent data.
+  * They are delivered to ease the usage or for better performance. Please,
+  * take a look at description of each class to get the details of their behavior.
+  */
+
 /** @defgroup synchronization Synchronization Primitives*/
 /** @defgroup primitives Primitives*/
 /** @defgroup exceptions Exceptions
diff --git a/include/libpmemobj++/container/array.hpp b/include/libpmemobj++/container/array.hpp
@@ -487,7 +487,7 @@ struct array {
 	 * @param[in] start start index of requested range.
 	 * @param[in] n number of elements in range.
 	 *
-	 * @return slice from start to start + n.
+	 * @return pmem::obj::slice from start to start + n.
 	 *
 	 * @throw std::out_of_range if any element of the range would be
 	 *	outside of the array.
@@ -515,7 +515,7 @@ struct array {
 	 *	added to a transaction. If value is equal to 0 no snapshotting
 	 *	happens.
 	 *
-	 * @return slice from start to start + n.
+	 * @return pmem::obj::slice from start to start + n.
 	 *
 	 * @throw std::out_of_range if any element of the range would be
 	 *	outside of the array.
@@ -543,7 +543,7 @@ struct array {
 	 * @param[in] start start index of requested range.
 	 * @param[in] n number of elements in range.
 	 *
-	 * @return slice from start to start + n.
+	 * @return pmem::obj::slice from start to start + n.
 	 *
 	 * @throw std::out_of_range if any element of the range would be
 	 *	outside of the array.
@@ -564,7 +564,7 @@ struct array {
 	 * @param[in] start start index of requested range.
 	 * @param[in] n number of elements in range.
 	 *
-	 * @return slice from start to start + n.
+	 * @return pmem::obj::slice from start to start + n.
 	 *
 	 * @throw std::out_of_range if any element of the range would be
 	 *	outside of the array.
diff --git a/include/libpmemobj++/container/basic_string.hpp b/include/libpmemobj++/container/basic_string.hpp
@@ -1397,7 +1397,7 @@ typename basic_string<CharT, Traits>::const_reference
  * @param[in] start start index of requested range.
  * @param[in] n number of elements in range.
  *
- * @return slice containing elements from <start, start + n).
+ * @return pmem::obj::slice containing elements from <start, start + n).
  *
  * @throw std::out_of_range if any element of the range would be outside of the
  * string.
@@ -1424,7 +1424,7 @@ basic_string<CharT, Traits>::range(size_type start, size_type n)
  * entire range is added to a transaction. If value is equal to 0 no
  * snapshotting happens.
  *
- * @return slice containing elements from <start, start + n).
+ * @return pmem::obj::slice containing elements from <start, start + n).
  *
  * @throw std::out_of_range if any element of the range would be outside of the
  * string.
@@ -1451,7 +1451,7 @@ basic_string<CharT, Traits>::range(size_type start, size_type n,
  * @param[in] start start index of requested range.
  * @param[in] n number of elements in range.
  *
- * @return slice containing elements from <start, start + n).
+ * @return pmem::obj::slice containing elements from <start, start + n).
  *
  * @throw std::out_of_range if any element of the range would be outside of the
  * string.
@@ -1469,7 +1469,7 @@ basic_string<CharT, Traits>::range(size_type start, size_type n) const
  * @param[in] start start index of requested range.
  * @param[in] n number of elements in range.
  *
- * @return slice containing elements from <start, start + n).
+ * @return pmem::obj::slice containing elements from <start, start + n).
  *
  * @throw std::out_of_range if any element of the range would be outside of the
  * string.
diff --git a/include/libpmemobj++/container/segment_vector.hpp b/include/libpmemobj++/container/segment_vector.hpp
@@ -1644,7 +1644,7 @@ segment_vector<T, Policy>::crend() const noexcept
  * @param[in] start start index of requested range.
  * @param[in] n number of elements in range.
  *
- * @return slice from start to start + n.
+ * @return pmem::obj::slice from start to start + n.
  *
  * @throw std::out_of_range if any element of the range would be outside
  * of the segment_vector.
@@ -1668,7 +1668,7 @@ segment_vector<T, Policy>::range(size_type start, size_type n)
  * @param[in] start start index of requested range.
  * @param[in] n number of elements in range.
  *
- * @return slice from start to start + n.
+ * @return pmem::obj::slice from start to start + n.
  *
  * @throw std::out_of_range if any element of the range would be outside
  * of the segment_vector.
@@ -1689,7 +1689,7 @@ segment_vector<T, Policy>::range(size_type start, size_type n) const
  * @param[in] start start index of requested range.
  * @param[in] n number of elements in range.
  *
- * @return slice from start to start + n.
+ * @return pmem::obj::slice from start to start + n.
  *
  * @throw std::out_of_range if any element of the range would be outside
  * of the segment_vector.
diff --git a/include/libpmemobj++/container/vector.hpp b/include/libpmemobj++/container/vector.hpp
@@ -1234,7 +1234,7 @@ vector<T>::crend() const noexcept
  * @param[in] start start index of requested range.
  * @param[in] n number of elements in range.
  *
- * @return slice from start to start + n.
+ * @return pmem::obj::slice from start to start + n.
  *
  * @throw std::out_of_range if any element of the range would be outside of the
  * vector.
@@ -1263,7 +1263,7 @@ vector<T>::range(size_type start, size_type n)
  * entire range is added to a transaction. If value is equal to 0 no
  * snapshotting happens.
  *
- * @return slice from start to start + n.
+ * @return pmem::obj::slice from start to start + n.
  *
  * @throw std::out_of_range if any element of the range would be outside of the
  * vector.
@@ -1292,7 +1292,7 @@ vector<T>::range(size_type start, size_type n, size_type snapshot_size)
  * @param[in] start start index of requested range.
  * @param[in] n number of elements in range.
  *
- * @return slice from start to start + n.
+ * @return pmem::obj::slice from start to start + n.
  *
  * @throw std::out_of_range if any element of the range would be outside of the
  * vector.
@@ -1314,7 +1314,7 @@ vector<T>::range(size_type start, size_type n) const
  * @param[in] start start index of requested range.
  * @param[in] n number of elements in range.
  *
- * @return slice from start to start + n.
+ * @return pmem::obj::slice from start to start + n.
  *
  * @throw std::out_of_range if any element of the range would be outside of the
  * vector.
diff --git a/include/libpmemobj++/experimental/inline_string.hpp b/include/libpmemobj++/experimental/inline_string.hpp
@@ -478,7 +478,7 @@ basic_inline_string_base<CharT, Traits>::at(size_type p) const
  * @param[in] start start index of requested range.
  * @param[in] n number of elements in range.
  *
- * @return slice from start to start + n.
+ * @return pmem::obj::slice from start to start + n.
  *
  * @throw std::out_of_range if any element of the range would be outside of the
  * container.
diff --git a/include/libpmemobj++/slice.hpp b/include/libpmemobj++/slice.hpp
@@ -43,8 +43,18 @@ namespace obj
 {
 
 /**
- * pmem::obj::slice - provides interface to access
- * sequence of objects.
+ * Provides interface to access sequence of objects.
+ *
+ * It provides the view of any sequence of objects and it simplifies the
+ * access to that sequence, with the help of iterators. It's used e.g. in
+ * several data structures to deliver `range` methods. As an example slice
+ * usage please see: pmem::obj::vector::range() .
+ *
+ * Slice can be used with any iterator type that supports:
+ * - indexing of elements - operator[],
+ * - subtraction of two iterators - operator-(),
+ * - pre-decrementing the iterator - operator--().
+ *
  * @ingroup data_view
  */
 template <typename Iterator>
@@ -56,8 +66,10 @@ class slice {
 	using reference = typename std::iterator_traits<iterator>::reference;
 
 	/**
-	 * Constructor taking two iterators (iterators should support:
-	 * operator[], operator-(), operator--()) which define a range.
+	 * Constructor taking two iterators, which define a range.
+	 *
+	 * @note These iterators have to support: operator[], operator-(), and
+	 * operator--()
 	 *
 	 * @throw std::out_of_range if it_end < it_begin.
 	 */
@@ -85,7 +97,7 @@ class slice {
 	slice &operator=(const slice &other) noexcept = default;
 
 	/**
-	 * Returns iterator to the beginning of the range.
+	 * @return iterator to the beginning of the slice's range.
 	 */
 	iterator
 	begin() const noexcept
@@ -94,7 +106,7 @@ class slice {
 	}
 
 	/**
-	 * Returns iterator to the end of the range.
+	 * @return iterator to the end of the slice's range.
 	 */
 	iterator
 	end() const noexcept
@@ -103,27 +115,39 @@ class slice {
 	}
 
 	/**
-	 * Returns reverse iterator to the end.
+	 * Returns a reverse_iterator to the last element in the range. Reverse
+	 * iterators iterate backwards: increasing them moves them towards the
+	 * beginning of the range.
+	 *
+	 * @return reverse_iterator to the reverse beginning of the slice's
+	 * range.
 	 */
 	reverse_iterator
-	rend() const noexcept
+	rbegin() const noexcept
 	{
-		return reverse_iterator(it_begin);
+		return reverse_iterator(it_end);
 	}
 
 	/**
-	 * Returns reverse iterator to the beginning.
+	 * Returns a reverse_iterator to the first element in the range. Reverse
+	 * iterators iterate backwards: increasing them moves them towards the
+	 * beginning of the range.
+	 *
+	 * @return reverse_iterator to the reverse end of the slice's range.
 	 */
 	reverse_iterator
-	rbegin() const noexcept
+	rend() const noexcept
 	{
-		return reverse_iterator(it_end);
+		return reverse_iterator(it_begin);
 	}
 
 	/**
-	 * Element access operator.
+	 * Access operator for a single element of slice.
+	 *
+	 * @param idx index of selected element.
 	 *
 	 * @throw std::out_of_range if idx is greater or equal to size.
+	 * @return reference to a selected object.
 	 */
 	reference
 	at(size_type idx)
@@ -136,15 +160,25 @@ class slice {
 	}
 
 	/**
-	 * Element access operator.
-	 * No bounds checking is performed.
+	 * Subscript operator, providing access to a single element of the
+	 * slice. It internally increments from begin iterator, @param idx
+	 * positions forward.
+	 *
+	 * @note No bounds checking is performed, so the iterator may become
+	 * invalid.
+	 * @return reference to a selected object.
 	 */
 	reference operator[](size_type idx)
 	{
 		return it_begin[static_cast<typename std::iterator_traits<
 			Iterator>::difference_type>(idx)];
 	}
 
+	/**
+	 * Returns total number of elements within slice's range.
+	 *
+	 * @return size_type count of all elements.
+	 */
 	size_type
 	size() const
 	{
diff --git a/include/libpmemobj++/string_view.hpp b/include/libpmemobj++/string_view.hpp
@@ -40,7 +40,8 @@ using u32string_view = std::basic_string_view<char32_t>;
  * Our partial std::string_view implementation.
  *
  * If C++17's std::string_view implementation is not available, this one
- * is used to avoid unnecessary string copying.
+ * is used to avoid unnecessary string copying. It's compatible with
+ * the std API, but it does not cover all functionalities.
  * @ingroup data_view
  */
 template <typename CharT, typename Traits = std::char_traits<CharT>>
@@ -161,9 +162,28 @@ class basic_string_view {
 	size_type size_;
 };
 
+/**
+ * The most typical string_view usage - the char specialization.
+ * @ingroup data_view
+ */
 using string_view = basic_string_view<char>;
+
+/**
+ * The wide char specialization.
+ * @ingroup data_view
+ */
 using wstring_view = basic_string_view<wchar_t>;
+
+/**
+ * The char16 specialization.
+ * @ingroup data_view
+ */
 using u16string_view = basic_string_view<char16_t>;
+
+/**
+ * The char32 specialization.
+ * @ingroup data_view
+ */
 using u32string_view = basic_string_view<char32_t>;
 
 /**

Original file line number	Diff line number	Diff line change
`@@ -487,7 +487,7 @@ struct array {`
`487`	`487`	`* @param[in] start start index of requested range.`
`488`	`488`	`* @param[in] n number of elements in range.`
`489`	`489`	`*`
`490`		`- * @return slice from start to start + n.`
	`490`	`+ * @return pmem::obj::slice from start to start + n.`
`491`	`491`	`*`
`492`	`492`	`* @throw std::out_of_range if any element of the range would be`
`493`	`493`	`* outside of the array.`
`@@ -515,7 +515,7 @@ struct array {`
`515`	`515`	`* added to a transaction. If value is equal to 0 no snapshotting`
`516`	`516`	`* happens.`
`517`	`517`	`*`
`518`		`- * @return slice from start to start + n.`
	`518`	`+ * @return pmem::obj::slice from start to start + n.`
`519`	`519`	`*`
`520`	`520`	`* @throw std::out_of_range if any element of the range would be`
`521`	`521`	`* outside of the array.`
`@@ -543,7 +543,7 @@ struct array {`
`543`	`543`	`* @param[in] start start index of requested range.`
`544`	`544`	`* @param[in] n number of elements in range.`
`545`	`545`	`*`
`546`		`- * @return slice from start to start + n.`
	`546`	`+ * @return pmem::obj::slice from start to start + n.`
`547`	`547`	`*`
`548`	`548`	`* @throw std::out_of_range if any element of the range would be`
`549`	`549`	`* outside of the array.`
`@@ -564,7 +564,7 @@ struct array {`
`564`	`564`	`* @param[in] start start index of requested range.`
`565`	`565`	`* @param[in] n number of elements in range.`
`566`	`566`	`*`
`567`		`- * @return slice from start to start + n.`
	`567`	`+ * @return pmem::obj::slice from start to start + n.`
`568`	`568`	`*`
`569`	`569`	`* @throw std::out_of_range if any element of the range would be`
`570`	`570`	`* outside of the array.`
Original file line number	Diff line number	Diff line change
`@@ -1397,7 +1397,7 @@ typename basic_string<CharT, Traits>::const_reference`
`1397`	`1397`	`* @param[in] start start index of requested range.`
`1398`	`1398`	`* @param[in] n number of elements in range.`
`1399`	`1399`	`*`
`1400`		`- * @return slice containing elements from <start, start + n).`
	`1400`	`+ * @return pmem::obj::slice containing elements from <start, start + n).`
`1401`	`1401`	`*`
`1402`	`1402`	`* @throw std::out_of_range if any element of the range would be outside of the`
`1403`	`1403`	`* string.`
`@@ -1424,7 +1424,7 @@ basic_string<CharT, Traits>::range(size_type start, size_type n)`
`1424`	`1424`	`* entire range is added to a transaction. If value is equal to 0 no`
`1425`	`1425`	`* snapshotting happens.`
`1426`	`1426`	`*`
`1427`		`- * @return slice containing elements from <start, start + n).`
	`1427`	`+ * @return pmem::obj::slice containing elements from <start, start + n).`
`1428`	`1428`	`*`
`1429`	`1429`	`* @throw std::out_of_range if any element of the range would be outside of the`
`1430`	`1430`	`* string.`
`@@ -1451,7 +1451,7 @@ basic_string<CharT, Traits>::range(size_type start, size_type n,`
`1451`	`1451`	`* @param[in] start start index of requested range.`
`1452`	`1452`	`* @param[in] n number of elements in range.`
`1453`	`1453`	`*`
`1454`		`- * @return slice containing elements from <start, start + n).`
	`1454`	`+ * @return pmem::obj::slice containing elements from <start, start + n).`
`1455`	`1455`	`*`
`1456`	`1456`	`* @throw std::out_of_range if any element of the range would be outside of the`
`1457`	`1457`	`* string.`
`@@ -1469,7 +1469,7 @@ basic_string<CharT, Traits>::range(size_type start, size_type n) const`
`1469`	`1469`	`* @param[in] start start index of requested range.`
`1470`	`1470`	`* @param[in] n number of elements in range.`
`1471`	`1471`	`*`
`1472`		`- * @return slice containing elements from <start, start + n).`
	`1472`	`+ * @return pmem::obj::slice containing elements from <start, start + n).`
`1473`	`1473`	`*`
`1474`	`1474`	`* @throw std::out_of_range if any element of the range would be outside of the`
`1475`	`1475`	`* string.`
Original file line number	Diff line number	Diff line change
`@@ -1644,7 +1644,7 @@ segment_vector<T, Policy>::crend() const noexcept`
`1644`	`1644`	`* @param[in] start start index of requested range.`
`1645`	`1645`	`* @param[in] n number of elements in range.`
`1646`	`1646`	`*`
`1647`		`- * @return slice from start to start + n.`
	`1647`	`+ * @return pmem::obj::slice from start to start + n.`
`1648`	`1648`	`*`
`1649`	`1649`	`* @throw std::out_of_range if any element of the range would be outside`
`1650`	`1650`	`* of the segment_vector.`
`@@ -1668,7 +1668,7 @@ segment_vector<T, Policy>::range(size_type start, size_type n)`
`1668`	`1668`	`* @param[in] start start index of requested range.`
`1669`	`1669`	`* @param[in] n number of elements in range.`
`1670`	`1670`	`*`
`1671`		`- * @return slice from start to start + n.`
	`1671`	`+ * @return pmem::obj::slice from start to start + n.`
`1672`	`1672`	`*`
`1673`	`1673`	`* @throw std::out_of_range if any element of the range would be outside`
`1674`	`1674`	`* of the segment_vector.`
`@@ -1689,7 +1689,7 @@ segment_vector<T, Policy>::range(size_type start, size_type n) const`
`1689`	`1689`	`* @param[in] start start index of requested range.`
`1690`	`1690`	`* @param[in] n number of elements in range.`
`1691`	`1691`	`*`
`1692`		`- * @return slice from start to start + n.`
	`1692`	`+ * @return pmem::obj::slice from start to start + n.`
`1693`	`1693`	`*`
`1694`	`1694`	`* @throw std::out_of_range if any element of the range would be outside`
`1695`	`1695`	`* of the segment_vector.`
Original file line number	Diff line number	Diff line change
`@@ -1234,7 +1234,7 @@ vector<T>::crend() const noexcept`
`1234`	`1234`	`* @param[in] start start index of requested range.`
`1235`	`1235`	`* @param[in] n number of elements in range.`
`1236`	`1236`	`*`
`1237`		`- * @return slice from start to start + n.`
	`1237`	`+ * @return pmem::obj::slice from start to start + n.`
`1238`	`1238`	`*`
`1239`	`1239`	`* @throw std::out_of_range if any element of the range would be outside of the`
`1240`	`1240`	`* vector.`
`@@ -1263,7 +1263,7 @@ vector<T>::range(size_type start, size_type n)`
`1263`	`1263`	`* entire range is added to a transaction. If value is equal to 0 no`
`1264`	`1264`	`* snapshotting happens.`
`1265`	`1265`	`*`
`1266`		`- * @return slice from start to start + n.`
	`1266`	`+ * @return pmem::obj::slice from start to start + n.`
`1267`	`1267`	`*`
`1268`	`1268`	`* @throw std::out_of_range if any element of the range would be outside of the`
`1269`	`1269`	`* vector.`
`@@ -1292,7 +1292,7 @@ vector<T>::range(size_type start, size_type n, size_type snapshot_size)`
`1292`	`1292`	`* @param[in] start start index of requested range.`
`1293`	`1293`	`* @param[in] n number of elements in range.`
`1294`	`1294`	`*`
`1295`		`- * @return slice from start to start + n.`
	`1295`	`+ * @return pmem::obj::slice from start to start + n.`
`1296`	`1296`	`*`
`1297`	`1297`	`* @throw std::out_of_range if any element of the range would be outside of the`
`1298`	`1298`	`* vector.`
`@@ -1314,7 +1314,7 @@ vector<T>::range(size_type start, size_type n) const`
`1314`	`1314`	`* @param[in] start start index of requested range.`
`1315`	`1315`	`* @param[in] n number of elements in range.`
`1316`	`1316`	`*`
`1317`		`- * @return slice from start to start + n.`
	`1317`	`+ * @return pmem::obj::slice from start to start + n.`
`1318`	`1318`	`*`
`1319`	`1319`	`* @throw std::out_of_range if any element of the range would be outside of the`
`1320`	`1320`	`* vector.`
Original file line number	Diff line number	Diff line change
`@@ -478,7 +478,7 @@ basic_inline_string_base<CharT, Traits>::at(size_type p) const`
`478`	`478`	`* @param[in] start start index of requested range.`
`479`	`479`	`* @param[in] n number of elements in range.`
`480`	`480`	`*`
`481`		`- * @return slice from start to start + n.`
	`481`	`+ * @return pmem::obj::slice from start to start + n.`
`482`	`482`	`*`
`483`	`483`	`* @throw std::out_of_range if any element of the range would be outside of the`
`484`	`484`	`* container.`