[Epydoc-commits] SF.net SVN: epydoc: [1393] branches/exp-args_in_class/epydoc/src/epydoc
Brought to you by:
edloper
Menu
▾
▴
[Epydoc-commits] SF.net SVN: epydoc: [1393] branches/exp-args_in_class/epydoc/src/epydoc
|
From: <dva...@us...> - 2006-09-16 00:02:18
|
Revision: 1393
http://svn.sourceforge.net/epydoc/?rev=1393&view=rev
Author: dvarrazzo
Date: 2006-09-15 17:02:10 -0700 (Fri, 15 Sep 2006)
Log Message:
-----------
- Reverted updates to `process_arg_field()` handler: is context is always a
function, not the class docstring.
- Exceptions are handled in the class docstring as well.
- More explicit name of some variables.
Modified Paths:
--------------
branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py
branches/exp-args_in_class/epydoc/src/epydoc/test/docbuilder.doctest
Modified: branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py 2006-09-15 23:36:23 UTC (rev 1392)
+++ branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py 2006-09-16 00:02:10 UTC (rev 1393)
@@ -308,7 +308,7 @@
var = tvar = par = tpar = None
for field in ff:
- if field.tag() in VAR_TAGS:
+ if field.tag() in VARIABLE_TAGS:
if var is None:
var = field
fields.append(field)
@@ -316,7 +316,7 @@
warnings.append(
"There is more than one variable named '%s'"
% arg)
- elif field.tag() in PARAM_TAGS:
+ elif field.tag() in PARAMETER_TAGS:
if par is None:
par = field
init_fields.append(field)
@@ -335,6 +335,9 @@
if par is not None and tpar is None:
tpar = field
+ elif field.tag() in EXCEPTION_TAGS:
+ init_fields.append(field)
+
else: # Unespected field
fields.append(field)
@@ -683,24 +686,15 @@
api_doc.return_type = descr
def process_arg_field(api_doc, docindex, tag, arg, descr):
- _check(api_doc, tag, arg, context=(ClassDoc, RoutineDoc), expect_arg=True)
+ _check(api_doc, tag, arg, context=RoutineDoc, expect_arg=True)
idents = re.split('[:;, ] *', arg)
+ api_doc.arg_descrs.append( (idents, descr) )
+ # Check to make sure that the documented parameter(s) are
+ # actually part of the function signature.
+ bad_params = ['"%s"' % i for i in idents if i not in api_doc.all_args()]
+ if bad_params:
+ raise ValueError(BAD_PARAM % (tag, ', '.join(bad_params)))
- if isinstance(api_doc, RoutineDoc):
- api_doc.arg_descrs.append( (idents, descr) )
-
- # Check to make sure that the documented parameter(s) are
- # actually part of the function signature.
- bad_params = ['"%s"' % i for i in idents if i not in api_doc.all_args()]
- if bad_params:
- raise ValueError(BAD_PARAM % (tag, ', '.join(bad_params)))
-
- elif isinstance(api_doc, ClassDoc):
- api_doc.init_args.append( (tag, arg, descr) )
-
- else:
- assert False, "unexpected context"
-
def process_kwarg_field(api_doc, docindex, tag, arg, descr):
# [xx] these should -not- be checked if they exist..
# and listed separately or not??
@@ -727,13 +721,15 @@
'except', 'exception')
# Tags related to function parameters
-PARAM_TAGS = ('arg', 'argument', 'parameter', 'param',
- 'kwarg', 'keyword', 'kwparam')
+PARAMETER_TAGS = ('arg', 'argument', 'parameter', 'param',
+ 'kwarg', 'keyword', 'kwparam')
# Tags related to variables in a class
-VAR_TAGS = ('cvar', 'cvariable',
- 'ivar', 'ivariable')
+VARIABLE_TAGS = ('cvar', 'cvariable', 'ivar', 'ivariable')
+# Tags related to exceptions
+EXCEPTION_TAGS = ('raise', 'raises', 'except', 'exception')
+
######################################################################
#{ Helper Functions
######################################################################
Modified: branches/exp-args_in_class/epydoc/src/epydoc/test/docbuilder.doctest
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/test/docbuilder.doctest 2006-09-15 23:36:23 UTC (rev 1392)
+++ branches/exp-args_in_class/epydoc/src/epydoc/test/docbuilder.doctest 2006-09-16 00:02:10 UTC (rev 1393)
@@ -245,6 +245,42 @@
+- posargs = ['self']
+- vararg = None
+Exceptions can be put in the docstring class, and they are assigned to the
+constructor too.
+ >>> runbuilder(s='''
+ ... class Foo:
+ ... """Foo(x, y)
+ ...
+ ... A class to ship rockets in outer space.
+ ...
+ ... @param x: first param
+ ... @param y: second param
+ ... @except ValueError: frobnication error
+ ... """
+ ... def __init__(self, a, b):
+ ... """__init__ doc"""
+ ... pass
+ ... ''',
+ ... build="Foo",
+ ... attribs="variables name value exception_descrs "
+ ... "posargs vararg kwarg type arg_types arg_descrs docstring")
+ ClassDoc for epydoc_test.Foo [0]
+ +- docstring = u'A class to ship rockets in outer sp...
+ +- variables
+ +- __init__ => VariableDoc for epydoc_test.Foo.__init__ [1]
+ +- docstring = <UNKNOWN>
+ +- name = '__init__'
+ +- value
+ +- RoutineDoc for epydoc_test.Foo.__init__ [2]
+ +- arg_descrs = [([u'x'], [u'first', u'param']), ...
+ +- arg_types = {}
+ +- docstring = u'__init__ doc'
+ +- exception_descrs = [(DottedName(u'ValueError'), ...
+ +- kwarg = None
+ +- posargs = [u'x', u'y']
+ +- vararg = None
+
+
Epydoc can also grok the constructor signature from the class docstring
>>> runbuilder(s='''
@@ -356,6 +392,10 @@
... `a` : string
... init param.
...
+ ... :Exceptions:
+ ... * `ValueError`: frobnication error
+ ... init param.
+ ...
... :IVariables:
... `a` : date
... instance var.
@@ -364,7 +404,7 @@
... pass
... ''',
... build="Foo",
- ... attribs="variables name value "
+ ... attribs="variables name value exception_descrs "
... "posargs vararg kwarg type_descr arg_types arg_descrs")
ClassDoc for epydoc_test.Foo [0]
+- variables
@@ -375,6 +415,7 @@
| +- RoutineDoc for epydoc_test.Foo.__init__ [2]
| +- arg_descrs = [([u'a'], [u'init', u'param.'])]
| +- arg_types = {u'a': [u'string']}
+ | +- exception_descrs = [(DottedName(u'ValueError'), ...
| +- kwarg = None
| +- posargs = ['self', 'a']
| +- vararg = None
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
