search

JonnyJD / epydoc-m

maintenance fork of epydoc
1 stars 2 forks source link

@diagnostics field #1

Open JonnyJD opened 12 years ago

JonnyJD commented 12 years ago

There is a patch at sourceforge implementing @diagnostics fields.

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

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.

JonnyJD commented 12 years ago

I am not sure yet if it will be included in master.

The reason I made the commit was mainly to track the patch.

I should note that you can actually create this field at run-time with

@newfield diagnostics: Diagnostics