clarify where \versionadded and \versionchanged should be placed when

they are used

1 files changed, 28 insertions, 20 deletions

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,15 +1018,37 @@ This \UNIX\ is also followed by a space.
       \macro{shortversion} macro.
     \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
+      pertains to.  This should be the last thing in the paragraph as
+      the end of the warning is not visually marked in any way.  The
+      content of \var{text} should be written in complete sentences
+      and include all appropriate punctuation.  This differs from
+      \macro{note} in that it is recommended over \macro{note} for
+      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.
-      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.
+      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}}
@@ -1034,22 +1056,8 @@ This \UNIX\ is also followed by a space.
       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
-      pertains to.  This should be the last thing in the paragraph as
-      the end of the warning is not visually marked in any way.  The
-      content of \var{text} should be written in complete sentences
-      and include all appropriate punctuation.  This differs from
-      \macro{note} in that it is recommended over \macro{note} for
-      information regarding security.
+      period will be appended by the formatting process.  This should
+      not generally be applied to modules.
     \end{macrodesc}