From 1d77bb33667df24eeff26cf09b94840e7daadbce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Thomas=20K=C3=B6ppe?= <tkoeppe@google.com>
Date: Tue, 14 Apr 2015 17:06:15 +0100
Subject: [PATCH] [containers] Make intra-synopsis comments consistent

---
 source/containers.tex | 112 +++++++++++++++++++++++-------------------
 1 file changed, 62 insertions(+), 50 deletions(-)

diff --git a/source/containers.tex b/source/containers.tex
index 7fe2a3db37..97e0e2da1f 100644
--- a/source/containers.tex
+++ b/source/containers.tex
@@ -2420,6 +2420,7 @@
 #include <initializer_list>
 
 namespace std {
+  // \ref{array}, class template array:
   template <class T, size_t N> struct array;
   template <class T, size_t N>
     bool operator==(const array<T, N>& x, const array<T, N>& y);
@@ -2461,6 +2462,7 @@
 #include <initializer_list>
 
 namespace std {
+  // \ref{deque}, class template deque:
   template <class T, class Allocator = allocator<T> > class deque;
   template <class T, class Allocator>
     bool operator==(const deque<T, Allocator>& x, const deque<T, Allocator>& y);
@@ -2488,6 +2490,7 @@
 #include <initializer_list>
 
 namespace std {
+  // \ref{forwardlist}, class template forward_list:
   template <class T, class Allocator = allocator<T> > class forward_list;
   template <class T, class Allocator>
     bool operator==(const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);
@@ -2515,6 +2518,7 @@
 #include <initializer_list>
 
 namespace std {
+  // \ref{list}, class template list:
   template <class T, class Allocator = allocator<T> > class list;
   template <class T, class Allocator>
     bool operator==(const list<T, Allocator>& x, const list<T, Allocator>& y);
@@ -2542,6 +2546,7 @@
 #include <initializer_list>
 
 namespace std {
+  // \ref{vector}, class template vector:
   template <class T, class Allocator = allocator<T> > class vector;
   template <class T, class Allocator>
     bool operator==(const vector<T, Allocator>& x, const vector<T, Allocator>& y);
@@ -2559,7 +2564,8 @@
     void swap(vector<T, Allocator>& x, vector<T, Allocator>& y)
       noexcept(noexcept(x.swap(y)));
 
-  template <class Allocator> class vector<bool,Allocator>;
+  // \ref{vector.bool}, class vector<bool>
+  template <class Allocator> class vector<bool, Allocator>;
 
   // hash support
   template <class T> struct hash;
@@ -2973,7 +2979,7 @@
   template <class T, class Allocator>
     bool operator<=(const deque<T, Allocator>& x, const deque<T, Allocator>& y);
 
-  // specialized algorithms:
+  // \ref{deque.special}, specialized algorithms:
   template <class T, class Allocator>
     void swap(deque<T, Allocator>& x, deque<T, Allocator>& y)
       noexcept(noexcept(x.swap(y)));
@@ -3362,7 +3368,6 @@
     void reverse() noexcept;
   };
 
-  // Comparison operators
   template <class T, class Allocator>
     bool operator==(const forward_list<T, Allocator>& x, const forward_list<T, Allocator>& y);
   template <class T, class Allocator>
@@ -4121,7 +4126,7 @@
   template <class T, class Allocator>
     bool operator<=(const list<T, Allocator>& x, const list<T, Allocator>& y);
 
-  // specialized algorithms:
+  // \ref{list.special}, specialized algorithms:
   template <class T, class Allocator>
     void swap(list<T, Allocator>& x, list<T, Allocator>& y)
       noexcept(noexcept(x.swap(y)));
@@ -5338,7 +5343,7 @@
 #include <initializer_list>
 
 namespace std {
-
+  // \ref{map}, class template map:
   template <class Key, class T, class Compare = less<Key>,
             class Allocator = allocator<pair<const Key, T> > >
     class map;
@@ -5365,6 +5370,7 @@
               map<Key, T, Compare, Allocator>& y)
       noexcept(noexcept(x.swap(y)));
 
+  // \ref{multimap}, class template multimap:
   template <class Key, class T, class Compare = less<Key>,
             class Allocator = allocator<pair<const Key, T> > >
     class multimap;
@@ -5400,7 +5406,7 @@
 #include <initializer_list>
 
 namespace std {
-
+  // \ref{set}, class template set:
   template <class Key, class Compare = less<Key>,
             class Allocator = allocator<Key> >
     class set;
@@ -5427,6 +5433,7 @@
               set<Key, Compare, Allocator>& y)
       noexcept(noexcept(x.swap(y)));
 
+  // \ref{set}, class template multiset:
   template <class Key, class Compare = less<Key>,
             class Allocator = allocator<Key> >
     class multiset;
@@ -5679,7 +5686,7 @@
     bool operator<=(const map<Key, T, Compare, Allocator>& x,
                     const map<Key, T, Compare, Allocator>& y);
 
-  // specialized algorithms:
+  // \ref{map.special}, specialized algorithms:
   template <class Key, class T, class Compare, class Allocator>
     void swap(map<Key, T, Compare, Allocator>& x,
               map<Key, T, Compare, Allocator>& y)
@@ -6056,7 +6063,7 @@
       }
     };
 
-    // construct/copy/destroy:
+    // \ref{multimap.cons}, construct/copy/destroy:
     multimap() : multimap(Compare()) { }
     explicit multimap(const Compare& comp, const Allocator& = Allocator());
     template <class InputIterator>
@@ -6105,7 +6112,7 @@
     size_type size() const noexcept;
     size_type max_size() const noexcept;
 
-    // modifiers:
+    // \ref{multimap.modifiers}, modifiers:
     template <class... Args> iterator emplace(Args&&... args);
     template <class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
     iterator insert(const value_type& x);
@@ -6177,7 +6184,7 @@
     bool operator<=(const multimap<Key, T, Compare, Allocator>& x,
                     const multimap<Key, T, Compare, Allocator>& y);
 
-  // specialized algorithms:
+  // \ref{multimap.special}, specialized algorithms:
   template <class Key, class T, class Compare, class Allocator>
     void swap(multimap<Key, T, Compare, Allocator>& x,
               multimap<Key, T, Compare, Allocator>& y)
@@ -6461,7 +6468,7 @@
     bool operator<=(const set<Key, Compare, Allocator>& x,
                     const set<Key, Compare, Allocator>& y);
 
-  // specialized algorithms:
+  // \ref{set.special}, specialized algorithms:
   template <class Key, class Compare, class Allocator>
     void swap(set<Key, Compare, Allocator>& x,
               set<Key, Compare, Allocator>& y)
@@ -6601,7 +6608,7 @@
     typedef std::reverse_iterator<iterator>       reverse_iterator;
     typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
 
-    // construct/copy/destroy:
+    // \ref{multiset.cons}, construct/copy/destroy:
     multiset() : multiset(Compare()) { }
     explicit multiset(const Compare& comp, const Allocator& = Allocator());
     template <class InputIterator>
@@ -6718,7 +6725,7 @@
     bool operator<=(const multiset<Key, Compare, Allocator>& x,
                     const multiset<Key, Compare, Allocator>& y);
 
-  // specialized algorithms:
+  // \ref{multiset.special}, specialized algorithms:
   template <class Key, class Compare, class Allocator>
     void swap(multiset<Key, Compare, Allocator>& x,
               multiset<Key, Compare, Allocator>& y)
@@ -6848,7 +6855,7 @@
   template <class Key, class T, class Hash, class Pred, class Alloc>
     bool operator!=(const unordered_multimap<Key, T, Hash, Pred, Alloc>& a,
                     const unordered_multimap<Key, T, Hash, Pred, Alloc>& b);
-} // namespace std
+}
 \end{codeblock}
 
 \rSec2[unord.set.syn]{Header \tcode{<unordered_set>} synopsis}%
@@ -6895,7 +6902,7 @@
   template <class Key, class Hash, class Pred, class Alloc>
     bool operator!=(const unordered_multiset<Key, Hash, Pred, Alloc>& a,
                     const unordered_multiset<Key, Hash, Pred, Alloc>& b);
-} // namespace std
+}
 \end{codeblock}
 
 \rSec2[unord.map]{Class template \tcode{unordered_map}}%
@@ -6932,7 +6939,7 @@
   class unordered_map
   {
   public:
-    // types
+    // types:
     typedef Key                                                 key_type;
     typedef std::pair<const Key, T>                             value_type;
     typedef T                                                   mapped_type;
@@ -6951,7 +6958,7 @@
     typedef @\impdef@                              local_iterator;
     typedef @\impdef@                              const_local_iterator;
 
-    // construct/destroy/copy
+    // \ref{unord.map.cnstr}, construct/copy/destroy:
     unordered_map();
     explicit unordered_map(size_type n,
                            const hasher& hf = hasher(),
@@ -6998,7 +7005,7 @@
     unordered_map& operator=(initializer_list<value_type>);
     allocator_type get_allocator() const noexcept;
 
-    // iterators
+    // iterators:
     iterator       begin() noexcept;
     const_iterator begin() const noexcept;
     iterator       end() noexcept;
@@ -7006,12 +7013,12 @@
     const_iterator cbegin() const noexcept;
     const_iterator cend() const noexcept;
 
-    // size and capacity
+    // capacity:
     bool      empty() const noexcept;
     size_type size() const noexcept;
     size_type max_size() const noexcept;
 
-    // modifiers
+    // \ref{unord.map.modifiers}, modifiers:
     template <class... Args> pair<iterator, bool> emplace(Args&&... args);
     template <class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
     pair<iterator, bool> insert(const value_type& obj);
@@ -7050,23 +7057,24 @@
                noexcept(swap(declval<Pred&>(), declval<Pred&>())));
     void      clear() noexcept;
 
-    // observers
+    // observers:
     hasher hash_function() const;
     key_equal key_eq() const;
 
-    // lookup
+    // map operations:
     iterator       find(const key_type& k);
     const_iterator find(const key_type& k) const;
     size_type      count(const key_type& k) const;
     std::pair<iterator, iterator>             equal_range(const key_type& k);
     std::pair<const_iterator, const_iterator> equal_range(const key_type& k) const;
 
+    // \ref{unord.map.elem} element access:
     mapped_type& operator[](const key_type& k);
     mapped_type& operator[](key_type&& k);
     mapped_type& at(const key_type& k);
     const mapped_type& at(const key_type& k) const;
 
-    // bucket interface
+    // bucket interface:
     size_type bucket_count() const noexcept;
     size_type max_bucket_count() const noexcept;
     size_type bucket_size(size_type n) const;
@@ -7078,7 +7086,7 @@
     const_local_iterator cbegin(size_type n) const;
     const_local_iterator cend(size_type n) const;
 
-    // hash policy
+    // hash policy:
     float load_factor() const noexcept;
     float max_load_factor() const noexcept;
     void max_load_factor(float z);
@@ -7093,6 +7101,7 @@
     bool operator!=(const unordered_map<Key, T, Hash, Pred, Alloc>& a,
                     const unordered_map<Key, T, Hash, Pred, Alloc>& b);
 
+  // \ref{unord.map.swap}, swap:
   template <class Key, class T, class Hash, class Pred, class Alloc>
     void swap(unordered_map<Key, T, Hash, Pred, Alloc>& x,
               unordered_map<Key, T, Hash, Pred, Alloc>& y)
@@ -7433,7 +7442,7 @@
   class unordered_multimap
   {
   public:
-    // types
+    // types:
     typedef Key                                                 key_type;
     typedef std::pair<const Key, T>                             value_type;
     typedef T                                                   mapped_type;
@@ -7452,7 +7461,7 @@
     typedef @\impdef@                              local_iterator;
     typedef @\impdef@                              const_local_iterator;
 
-    // construct/destroy/copy
+    // \ref{unord.multimap.cnstr}, construct/copy/destroy:
     unordered_multimap();
     explicit unordered_multimap(size_type n,
                                 const hasher& hf = hasher(),
@@ -7499,7 +7508,7 @@
     unordered_multimap& operator=(initializer_list<value_type>);
     allocator_type get_allocator() const noexcept;
 
-    // iterators
+    // iterators:
     iterator       begin() noexcept;
     const_iterator begin() const noexcept;
     iterator       end() noexcept;
@@ -7507,12 +7516,12 @@
     const_iterator cbegin() const noexcept;
     const_iterator cend() const noexcept;
 
-    // size and capacity
+    // capacity:
     bool      empty() const noexcept;
     size_type size() const noexcept;
     size_type max_size() const noexcept;
 
-    // modifiers
+    // \ref{unord.multimap.modifiers}, modifiers:
     template <class... Args> iterator emplace(Args&&... args);
     template <class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
     iterator insert(const value_type& obj);
@@ -7534,18 +7543,18 @@
                noexcept(swap(declval<Pred&>(), declval<Pred&>())));
     void      clear() noexcept;
 
-    // observers
+    // observers:
     hasher hash_function() const;
     key_equal key_eq() const;
 
-    // lookup
+    // map operations:
     iterator       find(const key_type& k);
     const_iterator find(const key_type& k) const;
     size_type      count(const key_type& k) const;
     std::pair<iterator, iterator>             equal_range(const key_type& k);
     std::pair<const_iterator, const_iterator> equal_range(const key_type& k) const;
 
-    // bucket interface
+    // bucket interface:
     size_type bucket_count() const noexcept;
     size_type max_bucket_count() const noexcept;
     size_type bucket_size(size_type n) const;
@@ -7572,6 +7581,7 @@
     bool operator!=(const unordered_multimap<Key, T, Hash, Pred, Alloc>& a,
                     const unordered_multimap<Key, T, Hash, Pred, Alloc>& b);
 
+  // \ref{unord.multimap.swap}, swap:
   template <class Key, class T, class Hash, class Pred, class Alloc>
     void swap(unordered_multimap<Key, T, Hash, Pred, Alloc>& x,
               unordered_multimap<Key, T, Hash, Pred, Alloc>& y)
@@ -7719,7 +7729,7 @@
   class unordered_set
   {
   public:
-    // types
+    // types:
     typedef Key                                                 key_type;
     typedef Key                                                 value_type;
     typedef Hash                                                hasher;
@@ -7737,7 +7747,7 @@
     typedef @\impdef@                              local_iterator;
     typedef @\impdef@                              const_local_iterator;
 
-    // construct/destroy/copy
+    // \ref{unord.set.cnstr}, construct/copy/destroy:
     unordered_set();
     explicit unordered_set(size_type n,
                            const hasher& hf = hasher(),
@@ -7784,7 +7794,7 @@
     unordered_set& operator=(initializer_list<value_type>);
     allocator_type get_allocator() const noexcept;
 
-    // iterators
+    // iterators:
     iterator       begin() noexcept;
     const_iterator begin() const noexcept;
     iterator       end() noexcept;
@@ -7792,12 +7802,12 @@
     const_iterator cbegin() const noexcept;
     const_iterator cend() const noexcept;
 
-    // size and capacity
+    // capacity:
     bool      empty() const noexcept;
     size_type size() const noexcept;
     size_type max_size() const noexcept;
 
-    // modifiers
+    // modifiers:
     template <class... Args> pair<iterator, bool> emplace(Args&&... args);
     template <class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
     pair<iterator, bool> insert(const value_type& obj);
@@ -7817,18 +7827,18 @@
                noexcept(swap(declval<Pred&>(), declval<Pred&>())));
     void      clear() noexcept;
 
-    // observers
+    // observers:
     hasher hash_function() const;
     key_equal key_eq() const;
 
-    // lookup
+    // set operations:
     iterator       find(const key_type& k);
     const_iterator find(const key_type& k) const;
     size_type      count(const key_type& k) const;
     std::pair<iterator, iterator>             equal_range(const key_type& k);
     std::pair<const_iterator, const_iterator> equal_range(const key_type& k) const;
 
-    // bucket interface
+    // bucket interface:
     size_type bucket_count() const noexcept;
     size_type max_bucket_count() const noexcept;
     size_type bucket_size(size_type n) const;
@@ -7840,7 +7850,7 @@
     const_local_iterator cbegin(size_type n) const;
     const_local_iterator cend(size_type n) const;
 
-    // hash policy
+    // hash policy:
     float load_factor() const noexcept;
     float max_load_factor() const noexcept;
     void max_load_factor(float z);
@@ -7855,6 +7865,7 @@
     bool operator!=(const unordered_set<Key, Hash, Pred, Alloc>& a,
                     const unordered_set<Key, Hash, Pred, Alloc>& b);
 
+  // \ref{unord.set.swap}, swap:
   template <class Key, class Hash, class Pred, class Alloc>
     void swap(unordered_set<Key, Hash, Pred, Alloc>& x,
               unordered_set<Key, Hash, Pred, Alloc>& y)
@@ -7971,7 +7982,7 @@
   class unordered_multiset
   {
   public:
-    // types
+    // types:
     typedef Key                                                 key_type;
     typedef Key                                                 value_type;
     typedef Hash                                                hasher;
@@ -7989,7 +8000,7 @@
     typedef @\impdef@                              local_iterator;
     typedef @\impdef@                              const_local_iterator;
 
-    // construct/destroy/copy
+    // \ref{unord.multiset.cnstr}, construct/copy/destroy:
     unordered_multiset();
     explicit unordered_multiset(size_type n,
                                 const hasher& hf = hasher(),
@@ -8036,7 +8047,7 @@
     unordered_multiset& operator=(initializer_list<value_type>);
     allocator_type get_allocator() const noexcept;
 
-    // iterators
+    // iterators:
     iterator       begin() noexcept;
     const_iterator begin() const noexcept;
     iterator       end() noexcept;
@@ -8044,12 +8055,12 @@
     const_iterator cbegin() const noexcept;
     const_iterator cend() const noexcept;
 
-    // size and capacity
+    // capacity:
     bool      empty() const noexcept;
     size_type size() const noexcept;
     size_type max_size() const noexcept;
 
-    // modifiers
+    // modifiers:
     template <class... Args> iterator emplace(Args&&... args);
     template <class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
     iterator insert(const value_type& obj);
@@ -8069,18 +8080,18 @@
                noexcept(swap(declval<Pred&>(), declval<Pred&>())));
     void      clear() noexcept;
 
-    // observers
+    // observers:
     hasher hash_function() const;
     key_equal key_eq() const;
 
-    // lookup
+    // set operations:
     iterator       find(const key_type& k);
     const_iterator find(const key_type& k) const;
     size_type      count(const key_type& k) const;
     std::pair<iterator, iterator>             equal_range(const key_type& k);
     std::pair<const_iterator, const_iterator> equal_range(const key_type& k) const;
 
-    // bucket interface
+    // bucket interface:
     size_type bucket_count() const noexcept;
     size_type max_bucket_count() const noexcept;
     size_type bucket_size(size_type n) const;
@@ -8092,7 +8103,7 @@
     const_local_iterator cbegin(size_type n) const;
     const_local_iterator cend(size_type n) const;
 
-    // hash policy
+    // hash policy:
     float load_factor() const noexcept;
     float max_load_factor() const noexcept;
     void max_load_factor(float z);
@@ -8107,6 +8118,7 @@
     bool operator!=(const unordered_multiset<Key, Hash, Pred, Alloc>& a,
                     const unordered_multiset<Key, Hash, Pred, Alloc>& b);
 
+  // \ref{unord.multiset.swap}, swap:
   template <class Key, class Hash, class Pred, class Alloc>
     void swap(unordered_multiset<Key, Hash, Pred, Alloc>& x,
               unordered_multiset<Key, Hash, Pred, Alloc>& y)