Merge lp:~dreid/twistedchecker/blank-lines-before-more-fields into lp:~twisted-dev/twistedchecker/trunk

[David Reid]

Not all epytext fields were properly recognized as the beginning of epytext blocks, this adds @cvar, @ivar, and @raises.

There may be others worth adding but these were the ones that were obviously in use and missing.

[lp:~dreid/twistedchecker/blank-lines-before-more-fields]

35. By David Reid on 2014-04-16

Also add @raise.

[Jean-Paul Calderone (exarkun)]

http://epydoc.sourceforge.net/fields.html#fields might be an interesting thing to consider here.

Perhaps it would be better not to try to match the particular keyword and instead just match something like `@[a-z]+`?

The code in the branch is, however, strictly an improvement over trunk. If you'd rather just land this as-is, that's fine with me too.

In other words, please consider making the code match all documented epytext keywords. If you'd rather not now, please file another bug report. Then merge.

Thank you very much for improving this!

review: Approve

=== modified file 'twistedchecker/checkers/docstring.py'
--- twistedchecker/checkers/docstring.py	2012-08-20 04:13:42 +0000
+++ twistedchecker/checkers/docstring.py	2014-04-16 20:13:17 +0000
@@ -207,7 +207,8 @@
         @param linenoDocstring: linenumber of docstring
         """
         # Check whether there is a blank line before epytext markups.
-        patternEpytext = (r"\n *@(param|type|return|returns|rtype)"
+        patternEpytext = (r"\n *@(param|type|return|returns|rtype|ivar|cvar"
+                          r"|raises|raise)"
                           r"\s*[a-zA-Z0-9_]*\s*\:")
         matchedEpytext = re.search(patternEpytext, node.doc)
         if matchedEpytext:

=== modified file 'twistedchecker/functionaltests/docstring_pass.py'
--- twistedchecker/functionaltests/docstring_pass.py	2012-08-20 04:13:42 +0000
+++ twistedchecker/functionaltests/docstring_pass.py	2014-04-16 20:13:17 +0000
@@ -62,3 +62,40 @@
         A method returns nothing.
         """
         return
+
+
+
+class Bar(self):
+    """
+    A cvar is recognized as being the start of epytext markup.
+
+    @cvar foo: bar baz
+    @type foo: bax
+    """
+
+    def a(self):
+        """
+        A raises field is recognized as being the start of epytext markup.
+
+        @raises FoobarException: An exception.
+        @returns: C{int}
+        """
+
+    def b(self):
+        """
+        A raise (because we are inconsistent about stuff) should also be
+        recognized as the start of epytext markup.
+
+        @raise BarException: Another exception.
+        @returns: C{int}
+        """
+
+
+
+class Baz(self):
+    """
+    An ivar is recognized as being the start of epytext markup.
+
+    @ivar foo: bar baz
+    @type foo: bax
+    """