diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
--- a/Doc/documenting/markup.rst
+++ b/Doc/documenting/markup.rst
@@ -200,8 +200,10 @@ The directives are:
 
 .. describe:: cmdoption
 
-   Describes a command line option or switch.  Option argument names should be
-   enclosed in angle brackets.  Example::
+   Describes a command-line option or switch of the Python interpreter.  This
+   construct will be turned into a link to the corresponding section of
+   :doc:`using/cmdline`.  Option argument names should be enclosed in angle
+   brackets.  Example::
 
       .. cmdoption:: -m <module>
 
@@ -503,7 +505,8 @@ in a different style:
 .. describe:: option
 
    A command-line option to an executable program.  The leading hyphen(s) must
-   be included.
+   be included.  May be used to document options accepted by modules run as
+   scripts (through ``python -m module``).
 
 .. describe:: program