[lib] Canonicalize order of library descriptive elements

Author: jensmaurer

source/iostreams.tex

@@ -3754,27 +3754,6 @@
 \end{itemdecl}
 
 \begin{itemdescr}
-\pnum
-\returns
-\tcode{traits::to_int_type(c)},
-where \tcode{c} is the first
-\textit{character}
-of the
-\term{pending sequence},
-without moving the input sequence position past it.
-If the pending sequence is null then the function returns
-\tcode{traits::eof()}
-to indicate failure.
-
-\pnum
-\remarks
-The public members of
-\tcode{basic_streambuf}
-call this virtual function only if
-\tcode{gptr()}
-is null or
-\tcode{gptr() >= egptr()}.
-
 \pnum
 The
 \term{pending sequence}
@@ -3840,10 +3819,31 @@
 agree with the backup sequence (where \tcode{n} is the length of the backup sequence).
 \end{itemize}
 
+\pnum
+\returns
+\tcode{traits::to_int_type(c)},
+where \tcode{c} is the first
+\textit{character}
+of the
+\term{pending sequence},
+without moving the input sequence position past it.
+If the pending sequence is null then the function returns
+\tcode{traits::eof()}
+to indicate failure.
+
 \pnum
 \default
 Returns
 \tcode{traits::eof()}.
+
+\pnum
+\remarks
+The public members of
+\tcode{basic_streambuf}
+call this virtual function only if
+\tcode{gptr()}
+is null or
+\tcode{gptr() >= egptr()}.
 \end{itemdescr}
 
 \indexlibrarymember{uflow}{basic_streambuf}%
@@ -3888,19 +3888,6 @@
 
 \begin{itemdescr}
 \pnum
-\remarks
-The public functions of
-\tcode{basic_streambuf}
-call this virtual function only when
-\tcode{gptr()}
-is null,
-\tcode{gptr() == eback()},
-or
-\tcode{traits::eq(traits::to_char_type(c), gptr()[-1])}
-returns
-\tcode{false}.
-Other calls shall also satisfy that constraint.
-
 The
 \term{pending sequence}
 is defined as for
@@ -3920,6 +3907,16 @@
 Whether the input sequence is backed up or modified in any other way is unspecified.
 \end{itemize}
 
+\pnum
+\ensures
+On return, the constraints of
+\tcode{gptr()},
+\tcode{eback()},
+and
+\tcode{pptr()}
+are the same as for
+\tcode{underflow()}.
+
 \pnum
 \returns
 \tcode{traits::eof()}
@@ -3934,20 +3931,24 @@
 \tcode{traits::eof()}
 to indicate success.
 
-\pnum
-\ensures
-On return, the constraints of
-\tcode{gptr()},
-\tcode{eback()},
-and
-\tcode{pptr()}
-are the same as for
-\tcode{underflow()}.
-
 \pnum
 \default
 Returns
 \tcode{traits::eof()}.
+
+\pnum
+\remarks
+The public functions of
+\tcode{basic_streambuf}
+call this virtual function only when
+\tcode{gptr()}
+is null,
+\tcode{gptr() == eback()},
+or
+\tcode{traits::eq(traits::to_char_type(c), gptr()[-1])}
+returns
+\tcode{false}.
+Other calls shall also satisfy that constraint.
 \end{itemdescr}
 
 \rSec4[streambuf.virt.put]{Put area}
@@ -4002,16 +4003,6 @@
 \tcode{true}, otherwise the sequence consisting of \tcode{c}.
 \end{itemize}
 
-\pnum
-\remarks
-The member functions
-\tcode{sputc()}
-and
-\tcode{sputn()}
-call this function in case that
-no room can be found in the put buffer enough to accommodate the
-argument character sequence.
-
 \pnum
 \expects
 Every overriding definition of this virtual function
@@ -4088,6 +4079,16 @@
 \default
 Returns
 \tcode{traits::eof()}.
+
+\pnum
+\remarks
+The member functions
+\tcode{sputc()}
+and
+\tcode{sputn()}
+call this function in case that
+no room can be found in the put buffer enough to accommodate the
+argument character sequence.
 \end{itemdescr}
 
 \rSec1[iostream.format]{Formatting and manipulators}
@@ -11083,6 +11084,16 @@
 if and only if a call was made to \tcode{sync()}
 since the most recent call to \tcode{emit()}, if any.
 
+\pnum
+\sync
+All \tcode{emit()} calls transferring characters
+to the same stream buffer object
+appear to execute in a total order
+consistent with the ``happens before'' relation\iref{intro.races},
+where each \tcode{emit()} call
+synchronizes with
+subsequent \tcode{emit()} calls in that total order.
+
 \pnum
 \ensures
 On success, the associated output is empty.
@@ -11097,16 +11108,6 @@
 \item The call to \tcode{wrapped->pubsync()} (if any) succeeded.
 \end{itemize}
 
-\pnum
-\sync
-All \tcode{emit()} calls transferring characters
-to the same stream buffer object
-appear to execute in a total order
-consistent with the ``happens before'' relation\iref{intro.races},
-where each \tcode{emit()} call
-synchronizes with
-subsequent \tcode{emit()} calls in that total order.
-
 \pnum
 \remarks
 May call member functions of \tcode{wrapped}

source/locales.tex

@@ -1829,16 +1829,6 @@
 set \tcode{from_next == from} and \tcode{to_next != to}.
 \end{note}
 
-\pnum
-\remarks
-Its operations on \tcode{state} are unspecified.
-\begin{note}
-This argument can be used, for example,
-to maintain shift state,
-to specify conversion options (such as count only), or
-to identify a cache of seek offsets.
-\end{note}
-
 \pnum
 \returns
 An enumeration value, as summarized in \tref{locale.codecvt.inout}.
@@ -1864,6 +1854,16 @@
 all the available destination elements, or
 that additional source elements are needed
 before another destination element can be produced.
+
+\pnum
+\remarks
+Its operations on \tcode{state} are unspecified.
+\begin{note}
+This argument can be used, for example,
+to maintain shift state,
+to specify conversion options (such as count only), or
+to identify a cache of seek offsets.
+\end{note}
 \end{itemdescr}
 
 \indexlibrarymember{codecvt}{do_unshift}%

source/numerics.tex

@@ -4340,24 +4340,6 @@
 \end{itemdecl}
 
 \begin{itemdescr}
-\pnum
-\complexity
-Exactly
- $k = \max(1, \left\lceil b / \log_2 R \right\rceil)$
- invocations
- of \tcode{g},
- where $b$
-\begin{footnote}
-$b$ is introduced
-   to avoid any attempt
-   to produce more bits of randomness
-   than can be held in \tcode{RealType}.
-\end{footnote}
-   is the lesser of \tcode{numeric_limits<RealType>::digits}
-                and \tcode{bits},
- and
-   $R$ is the value of $\tcode{g.max()} - \tcode{g.min()} + 1$.
-
 \pnum
 \effects
  Invokes \tcode{g()} $k$ times
@@ -4381,6 +4363,24 @@
 \throws
 What and when \tcode{g} throws.
 
+\pnum
+\complexity
+Exactly
+ $k = \max(1, \left\lceil b / \log_2 R \right\rceil)$
+ invocations
+ of \tcode{g},
+ where $b$
+\begin{footnote}
+$b$ is introduced
+   to avoid any attempt
+   to produce more bits of randomness
+   than can be held in \tcode{RealType}.
+\end{footnote}
+   is the lesser of \tcode{numeric_limits<RealType>::digits}
+                and \tcode{bits},
+ and
+   $R$ is the value of $\tcode{g.max()} - \tcode{g.min()} + 1$.
+
 \pnum
 \begin{note}
 If the values $g_i$ produced by \tcode{g} are uniformly distributed,

source/regex.tex

@@ -1538,10 +1538,6 @@
 \end{itemdecl}
 
 \begin{itemdescr}
-\pnum
-\returns
-\tcode{*this}.
-
 \pnum
 \effects
 Assigns the regular expression contained in the string
@@ -1554,6 +1550,10 @@
 \tcode{flags()} returns \tcode{f} and \tcode{mark_count()}
 returns the number of marked sub-expressions within the expression.
 
+\pnum
+\returns
+\tcode{*this}.
+
 \pnum
 \throws
 \tcode{regex_error} if \tcode{s} is not a valid regular expression.

source/utilities.tex

@@ -9892,10 +9892,6 @@
 \end{itemdecl}
 
 \begin{itemdescr}
-\pnum
-\mandates
-\tcode{Y} is a complete type.
-
 \pnum
 \constraints
 When \tcode{T} is an array type,
@@ -9906,6 +9902,10 @@
 the expression \tcode{delete p} is well-formed and
 \tcode{Y*} is convertible to \tcode{T*}.
 
+\pnum
+\mandates
+\tcode{Y} is a complete type.
+
 \pnum
 \expects
 The expression
@@ -10363,16 +10363,16 @@
 \end{itemdecl}
 
 \begin{itemdescr}
+\pnum
+\sync
+None.
+
 \pnum
 \returns
 The number of \tcode{shared_ptr} objects, \tcode{*this} included,
 that share ownership with \tcode{*this}, or \tcode{0} when \tcode{*this} is
 empty.
 
-\pnum
-\sync
-None.
-
 \pnum
 \begin{note}
 \tcode{get() == nullptr}