docs: add docs for WD_UNDERLINE enumeration

Steve Canny · Steve Canny · commit fc965c241901 · 2014-05-13T00:20:20.000-07:00
diff --git a/docs/api/enum/WdUnderline.rst b/docs/api/enum/WdUnderline.rst
@@ -0,0 +1,69 @@
+.. _WdUnderline:
+
+``WD_UNDERLINE``
+================
+
+Specifies the style of underline applied to a run of characters.
+
+----
+
+NONE
+    No underline. This setting overrides any inherited underline value, so can
+    be used to remove underline from a run that inherits underlining from its
+    containing paragraph. Note this is not the same as assigning |None| to
+    Run.underline. |None| is a valid assignment value, but causes the run to
+    inherit its underline value. Assigning ``WD_UNDERLINE.NONE`` causes
+    underlining to be unconditionally turned off.
+
+SINGLE
+    A single line. Note that this setting is write-only in the sense that
+    |True| (rather than ``WD_UNDERLINE.SINGLE``) is returned for a run having
+    this setting.
+
+WORDS
+    Underline individual words only.
+
+DOUBLE
+    A double line.
+
+DOTTED
+    Dots.
+
+THICK
+    A single thick line.
+
+DASH
+    Dashes.
+
+DOT_DASH
+    Alternating dots and dashes.
+
+DOT_DOT_DASH
+    An alternating dot-dot-dash pattern.
+
+WAVY
+    A single wavy line.
+
+DOTTED_HEAVY
+    Heavy dots.
+
+DASH_HEAVY
+    Heavy dashes.
+
+DOT_DASH_HEAVY
+    Alternating heavy dots and heavy dashes.
+
+DOT_DOT_DASH_HEAVY
+    An alternating heavy dot-dot-dash pattern.
+
+WAVY_HEAVY
+    A heavy wavy line.
+
+DASH_LONG
+    Long dashes.
+
+WAVY_DOUBLE
+    A double wavy line.
+
+DASH_LONG_HEAVY
+    Long heavy dashes.
diff --git a/docs/api/enum/index.rst b/docs/api/enum/index.rst
@@ -0,0 +1,11 @@
+
+Enumerations
+============
+
+Documentation for the various enumerations used for |docx| property settings
+can be found here:
+
+.. toctree::
+   :titlesonly:
+
+   WdUnderline
diff --git a/docs/dev/analysis/features/underline.rst b/docs/dev/analysis/features/underline.rst
@@ -87,6 +87,9 @@ Directly-applied no-underline, overrides inherited value::
 Schema excerpt
 --------------
 
+Note that the ``w:val`` attribute on ``CT_Underline`` is optional. When it is
+not present no underline appears on the run.
+
 .. highlight:: xml
 
 ::
diff --git a/docs/index.rst b/docs/index.rst
@@ -84,6 +84,7 @@ API Documentation
    api/text
    api/shape
    api/shared
+   api/enum/index
 
 
 Contributor Guide
diff --git a/docx/enum/text.py b/docx/enum/text.py
@@ -47,11 +47,15 @@ class WD_UNDERLINE(XmlEnumeration):
             'NONE', 0, 'none', 'No underline. This setting overrides any inh'
             'erited underline value, so can be used to remove underline from'
             ' a run that inherits underlining from its containing paragraph.'
+            ' Note this is not the same as assigning |None| to Run.underline'
+            '. |None| is a valid assignment value, but causes the run to inh'
+            'erit its underline value. Assigning ``WD_UNDERLINE.NONE`` cause'
+            's underlining to be unconditionally turned off.'
         ),
         XmlMappedEnumMember(
-            'SINGLE', 1, 'single', 'A single line (default). Note that this '
-            'setting is write-only in the sense that |True| (rather than 1) '
-            'is returned for a run having this setting.'
+            'SINGLE', 1, 'single', 'A single line. Note that this setting is'
+            'write-only in the sense that |True| (rather than ``WD_UNDERLINE'
+            '.SINGLE``) is returned for a run having this setting.'
         ),
         XmlMappedEnumMember(
             'WORDS', 2, 'words', 'Underline individual words only.'
diff --git a/docx/text.py b/docx/text.py
@@ -333,14 +333,14 @@ def text(self):
     def underline(self):
         """
         The underline style for this |Run|, one of |None|, |True|, |False|,
-        or a value from ``pptx.enum.text.WD_UNDERLINE``. A value of |None|
-        indicates the run has no directly-applied underline value and so will
-        inherit the underline value of its containing paragraph. Assigning
-        |None| to this property removes any directly-applied underline value.
-        A value of |False| indicates a directly-applied setting of no
-        underline, overriding any inherited value. A value of |True|
-        indicates single underline. The values from ``WD_UNDERLINE`` are used
-        to specify other outline styles such as double, wavy, and dotted.
+        or a value from :ref:`WdUnderline`. A value of |None| indicates the
+        run has no directly-applied underline value and so will inherit the
+        underline value of its containing paragraph. Assigning |None| to this
+        property removes any directly-applied underline value. A value of
+        |False| indicates a directly-applied setting of no underline,
+        overriding any inherited value. A value of |True| indicates single
+        underline. The values from ``WD_UNDERLINE`` are used to specify other
+        outline styles such as double, wavy, and dotted.
         """
         return self._r.underline
 
