add @diagnostics field - sf id: 1887564, re #1

doc/manual-fields.txt

@@ -253,6 +253,16 @@ Notes and Warnings
     An important note about an object. Multiple attention fields may be
     used to list separate notes.
 
+``@diagnostics``: ...
+    A description of a diagnostic message raised by an object. Multiple
+    diagnostics fields may be used to report separate diagnostic messages.
+
+    .. note::
+
+        If any ``@diagnostics`` field is used, the HTML writer will generate a
+        the page ``diagnostics-index.html``, containing links to all the items
+        tagged with the field.
+
 ``@bug``: ...
     A description of a bug in an object. Multiple bug fields may be used to
     report separate bugs.

doc/manual-usage.txt

@@ -292,6 +292,10 @@ The following list describes each of the files generated by epydoc:
     The index of all the term definition found in the docstrings. Term
     definitions are created using the `Indexed Terms`_ markup.
 
+``diagnostics-index.html``
+    The index of all the known diagnostic messages in the documented sources.
+    Diagnostics are marked using the ``@diagnostics`` tag.
+
 ``bug-index.html``
     The index of all the known bug in the documented sources. Bugs are marked
     using the ``@bug`` tag.

doc/using.html

@@ -369,8 +369,12 @@ <h2 class="box-title">Example Configuration File</h2>
   Term definitions are created using the <a href="epytext.html#indexed">Indexed
   Term</a> markup. </li>
 
+  <li><b><code>diagnostics-index.html</code></b>
+  The index of all known diagnostic messages in the documented sources.
+  Diagnostic messages are maked using the <code>@diagnostics</code> tag. </li>
+
   <li><b><code>bug-index.html</code></b>
-  The index of all the known bug in the documented sources.
+  The index of all the known bugs in the documented sources.
   Bugs are marked using the <code>@bug</code> tag. </li>
 
   <li><b><code>todo-index.html</code></b>

man/epydoc.1

@@ -429,6 +429,14 @@ generated if at least one
 .B @bug
 field is listed in a formatted docstring.
 .TP
+.B diagnostics-index.html
+An index of all explicitly marked
+.B @diagnostics
+fields.  This page is only
+generated if at least one
+.B @diagnostics
+field is listed in a formatted docstring.
+.TP
 .B todo-index.html
 An index of all explicitly marked
 .B @todo

src/epydoc/docstringparser.py

@@ -131,6 +131,7 @@ def __repr__(self):
     DocstringField(['warning', 'warn'], 'Warning', 'Warnings'),
     DocstringField(['attention'], 'Attention'),
     DocstringField(['note'], 'Note', 'Notes'),
+    DocstringField(['diagnostics', 'diagnostic'], 'Diagnostics', 'Diagnostics'),
 
     # Formal conditions
     DocstringField(['requires', 'require', 'requirement'], 'Requires'),

src/epydoc/docwriter/html.py

@@ -2921,7 +2921,8 @@ def write_standard_fields(self, out, doc):
     #: where C{tag} is the cannonical tag of a metadata field;
     #: C{label} is a label for the index page; and C{short_label}
     #: is a shorter label, used in the index selector.
-    METADATA_INDICES = [('bug', 'Bug List', 'Bugs'),
+    METADATA_INDICES = [('diagnostics', 'Diagnostics', 'Diagnostics'),
+                        ('bug', 'Bug List', 'Bugs'),
                         ('todo', 'To Do List', 'To Do'),
                         ('change', 'Change Log', 'Changes'),
                         ('deprecated', 'Deprecation List', 'Deprecations'),