Browse files

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

This patch adds a new field, called @diagnostics, which is treated like
other indexed fields, such as @todo, and @bug.

The idea behind the patch is to allow developers to create diagnostics
sections in their documentation, that contains a list of error messages
that the code generates, along with a snippet of text about what it
means. For example:

@diagnostics: C{Unrecognized token in config file: %s}

The config file contained an invalid token. This may be caused by a
typo, if you edited the file by hand, or the pluralization of a keyword
where the singular was expected. If you haven't changed the file by
hand, the config file may have been created with an earlier version of
the software, which had a slightly different format. See the "Config
Files" section if the upgrade documentation.

The attached patch fixes the epydoc docstring parser, docwriter, and the
documentation. It makes no changes to documentation generated in Latex,
or with the javaDoc or reStructuredText formats.

Testing has been adhoc, and no additional test cases were added to the
doctests.

https://sourceforge.net/support/tracker.php?aid=1887564

Signed-off-by: Johannes Dewender <github@JonnyJD.net>
  • Loading branch information...
1 parent 269780a commit 38c4468c355f4c8aa7dfd1943e33ab4e06ca37f5 Ammon Riley committed with Feb 5, 2008
Showing with 30 additions and 2 deletions.
  1. +10 −0 doc/manual-fields.txt
  2. +4 −0 doc/manual-usage.txt
  3. +5 −1 doc/using.html
  4. +8 −0 man/epydoc.1
  5. +1 −0 src/epydoc/docstringparser.py
  6. +2 −1 src/epydoc/docwriter/html.py
View
10 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.
View
4 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.
View
6 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>
View
8 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
View
1 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'),
View
3 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'),

0 comments on commit 38c4468

Please sign in to comment.