@@ -43,8 +43,18 @@ namespace obj
4343{
4444
4545/* *
46- * pmem::obj::slice - provides interface to access
47- * sequence of objects.
46+ * Provides interface to access sequence of objects.
47+ *
48+ * It provides the view of any sequence of objects and it simplifies the
49+ * access to that sequence, with the help of iterators. It's used e.g. in
50+ * several data structures to deliver `range` methods. As an example slice
51+ * usage please see: pmem::obj::vector::range() .
52+ *
53+ * Slice can be used with any iterator type that supports:
54+ * - indexing of elements - operator[],
55+ * - subtraction of two iterators - operator-(),
56+ * - pre-decrementing the iterator - operator--().
57+ *
4858 * @ingroup data_view
4959 */
5060template <typename Iterator>
@@ -56,8 +66,10 @@ class slice {
5666 using reference = typename std::iterator_traits<iterator>::reference;
5767
5868 /* *
59- * Constructor taking two iterators (iterators should support:
60- * operator[], operator-(), operator--()) which define a range.
69+ * Constructor taking two iterators, which define a range.
70+ *
71+ * @note These iterators have to support: operator[], operator-(), and
72+ * operator--()
6173 *
6274 * @throw std::out_of_range if it_end < it_begin.
6375 */
@@ -85,7 +97,7 @@ class slice {
8597 slice &operator =(const slice &other) noexcept = default ;
8698
8799 /* *
88- * Returns iterator to the beginning of the range.
100+ * @return iterator to the beginning of the slice's range.
89101 */
90102 iterator
91103 begin () const noexcept
@@ -94,7 +106,7 @@ class slice {
94106 }
95107
96108 /* *
97- * Returns iterator to the end of the range.
109+ * @return iterator to the end of the slice's range.
98110 */
99111 iterator
100112 end () const noexcept
@@ -103,27 +115,39 @@ class slice {
103115 }
104116
105117 /* *
106- * Returns reverse iterator to the end.
118+ * Returns a reverse_iterator to the last element in the range. Reverse
119+ * iterators iterate backwards: increasing them moves them towards the
120+ * beginning of the range.
121+ *
122+ * @return reverse_iterator to the reverse beginning of the slice's
123+ * range.
107124 */
108125 reverse_iterator
109- rend () const noexcept
126+ rbegin () const noexcept
110127 {
111- return reverse_iterator (it_begin );
128+ return reverse_iterator (it_end );
112129 }
113130
114131 /* *
115- * Returns reverse iterator to the beginning.
132+ * Returns a reverse_iterator to the first element in the range. Reverse
133+ * iterators iterate backwards: increasing them moves them towards the
134+ * beginning of the range.
135+ *
136+ * @return reverse_iterator to the reverse end of the slice's range.
116137 */
117138 reverse_iterator
118- rbegin () const noexcept
139+ rend () const noexcept
119140 {
120- return reverse_iterator (it_end );
141+ return reverse_iterator (it_begin );
121142 }
122143
123144 /* *
124- * Element access operator.
145+ * Access operator for a single element of slice.
146+ *
147+ * @param idx index of selected element.
125148 *
126149 * @throw std::out_of_range if idx is greater or equal to size.
150+ * @return reference to a selected object.
127151 */
128152 reference
129153 at (size_type idx)
@@ -136,15 +160,25 @@ class slice {
136160 }
137161
138162 /* *
139- * Element access operator.
140- * No bounds checking is performed.
163+ * Subscript operator, providing access to a single element of the
164+ * slice. It internally increments from begin iterator, @param idx
165+ * positions forward.
166+ *
167+ * @note No bounds checking is performed, so the iterator may become
168+ * invalid.
169+ * @return reference to a selected object.
141170 */
142171 reference operator [](size_type idx)
143172 {
144173 return it_begin[static_cast <typename std::iterator_traits<
145174 Iterator>::difference_type>(idx)];
146175 }
147176
177+ /* *
178+ * Returns total number of elements within slice's range.
179+ *
180+ * @return size_type count of all elements.
181+ */
148182 size_type
149183 size () const
150184 {
0 commit comments