#259 Can't reference exceptions referenced via external API

[André Malo]

Hi,

it's rather restructuredtext, but anyway:

There is no (at least no obvious) way to reference exceptions that are included as external API.
For example:

:Exceptions:
- :foo:`some.where.ElseError`: blahr

I figured this is mainly because the consolidated field splitter expects a 'title_reference' here, which it isn't. Extending the check to allow 'reference's as well doesn't work either, because after swallowing that epydoc looks for 'ElseError' in the local tree only. I gave up at this point and tried various combinations of stand-alone :except: fields, but no luck.

[Edward Loper]

Logged In: YES
user_id=195958
Originator: NO

Unfortunately, there's not any easy solution for this. The class epydoc uses to store field information, epydoc.markup.Field, defines 3 attributes: a name, an arg, and a body. The problem is that the arg is defined to be a simple string (i.e., it doesn't contain any markup).

Doing what you want would require either changing Field.arg to contain a ParsedDocstring instead of a string (which would require adjusting every part of epydoc that processes fields); or doing some kind of special-case hacking for exception fields. Neither solution is particularly attractive. :-/

A work-around is to define a new field that looks very similar to the existing 'except' field. Add the following to your module/package docstring (you might want to pick a better name):

"""
:newfield except2: Raises
"""

And then you can use it as follows in functions:

def f(x):
"""
:except2: :foo:`foo.bar.baz`: etc..
:except2: :foo:`org.apache.uima.cas.CAS`: etc..

But note that if you mix this new field and the existing :except: field, in a single docstring, the output will generate two separate lists of exceptions, which will look a little odd.