clarify where \versionadded and \versionchanged should be placed when
they are used
diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex
index c56473d..60bf15d 100644
--- a/Doc/doc/doc.tex
+++ b/Doc/doc/doc.tex
@@ -1018,29 +1018,6 @@
\macro{shortversion} macro.
\end{macrodesc}
- \begin{macrodesc}{versionadded}{\op{explanation}\p{version}}
- The version of Python which added the described feature to the
- library or C API. \var{explanation} should be a \emph{brief}
- explanation of the change consisting of a capitalized sentence
- fragment; a period will be appended by the formatting process.
- This is typically added to the end of the first paragraph of the
- description before any availability notes. The location should
- be selected so the explanation makes sense and may vary as
- needed.
- \end{macrodesc}
-
- \begin{macrodesc}{versionchanged}{\op{explanation}\p{version}}
- The version of Python in which the named feature was changed in
- some way (new parameters, changed side effects, etc.).
- \var{explanation} should be a \emph{brief} explanation of the
- change consisting of a capitalized sentence fragment; a
- period will be appended by the formatting process.
- This is typically added to the end of the first paragraph of the
- description before any availability notes and after
- \macro{versionadded}. The location should be selected so the
- explanation makes sense and may vary as needed.
- \end{macrodesc}
-
\begin{macrodesc}{warning}{\p{text}}
An important bit of information about an API that a user should
be very aware of when using whatever bit of API the warning
@@ -1052,6 +1029,37 @@
information regarding security.
\end{macrodesc}
+ The following two macros are used to describe information that's
+ associated with changes from one release to another. For features
+ which are described by a single paragraph, these are typically
+ added as separate source lines at the end of the paragraph. When
+ adding these to features described by multiple paragraphs, they
+ are usually collected in a single separate paragraph after the
+ description. When both \macro{versionadded} and
+ \macro{versionchanged} are used, \macro{versionadded} should come
+ first; the versions should be listed in chronological order. Both
+ of these should come before availability statements. The location
+ should be selected so the explanation makes sense and may vary as
+ needed.
+
+ \begin{macrodesc}{versionadded}{\op{explanation}\p{version}}
+ The version of Python which added the described feature to the
+ library or C API. \var{explanation} should be a \emph{brief}
+ explanation of the change consisting of a capitalized sentence
+ fragment; a period will be appended by the formatting process.
+ When this applies to an entire module, it should be placed at
+ the top of the module section before any prose.
+ \end{macrodesc}
+
+ \begin{macrodesc}{versionchanged}{\op{explanation}\p{version}}
+ The version of Python in which the named feature was changed in
+ some way (new parameters, changed side effects, etc.).
+ \var{explanation} should be a \emph{brief} explanation of the
+ change consisting of a capitalized sentence fragment; a
+ period will be appended by the formatting process. This should
+ not generally be applied to modules.
+ \end{macrodesc}
+
\subsection{Miscellaneous Text Markup \label{misc-text-markup}}