epyDoc Questions

[Neil Benn]

Hello,

I can;t find a epyDoc specific mailing list, so I'll try here
- if you know of a epyDoc mailing list then please let me know (google
is not my friend, I can only find an announce, devel and commit list
from 'epydoc mailing list').

I'm working on marking up a class in epyDoc and have a few things
that I strongly suspect I can do but can't find instructions for in the
docs - I was hoping that someone has cracked this already:

1. I want to document the attributes (instance and also class) of a
class and or module, I know the tags are there - where does they
go (before/after theclass decleration, top of the module, if
someone puts in the class doc but misses out the module stuff, how
will epydoc know that this is meant to be class and not module
(although someone doing this will probably get shouted at in a
code review!)?
2. In the argument to the tag for raises, how can I put a link
through to the exception?
3. How would I go about marking up the property docs so that it knows
what the setter and getter methods are - it links through to the
methods but the docs arn't in there, they are in the fifth
argument to the property method (I can manually do this using
sections but is there a tag I can use?)

Cheers for your help,

Neil

--

Neil Benn
Senior Automation Engineer
Cenix BioScience
BioInnovations Zentrum
Tatzberg 47
D-01307
Dresden
Germany

Tel : [phone]
e-mail : be**@cenix-bioscience.com
Cenix Website : http://www.cenix-bioscience.com

[Colin J. Williams]

Neil Benn wrote:

Hello,

I can;t find a epyDoc specific mailing list, so I'll try here -
if you know of a epyDoc mailing list then please let me know (google is
not my friend, I can only find an announce, devel and commit list from
'epydoc mailing list').
epyDoc gives nice documentation with no mark-up. I've not seen any
indication of maintenance for a year or so. I'm working on marking up a class in epyDoc and have a few things
that I strongly suspect I can do but can't find instructions for in the
docs - I was hoping that someone has cracked this already:

1. I want to document the attributes (instance and also class) of a
class and or module, I know the tags are there - where does they
go (before/after theclass decleration, top of the module, if
someone puts in the class doc but misses out the module stuff, how
will epydoc know that this is meant to be class and not module
(although someone doing this will probably get shouted at in a
code review!)? Why not post some code so that we can more clearly understand what you
aim to document?

Colin W. 2. In the argument to the tag for raises, how can I put a link
through to the exception?
3. How would I go about marking up the property docs so that it knows
what the setter and getter methods are - it links through to the
methods but the docs arn't in there, they are in the fifth
argument to the property method (I can manually do this using
sections but is there a tag I can use?)

Cheers for your help,

Neil

[Jeffrey E. Forcier]

Neil Benn wrote:

1. I want to document the attributes (instance and also class) of a
class and or module, I know the tags are there - where does they
go (before/after theclass decleration, top of the module, if
someone puts in the class doc but misses out the module stuff, how
will epydoc know that this is meant to be class and not module
(although someone doing this will probably get shouted at in a
code review!)?
http://epydoc.sourceforge.net/fields.html

You specify different tags for class, instance and module level
attributes/variables using the respective tags @cvar, @ivar and @var. I
believe you need to put @cvar and @ivar in the class' docstring, as
follows:
## code ##
class MyClass():
"""
Stuff.

@cvar varOne: the first var
@cvar varTwo: the second var
"""
varOne = 1
varTwo = 2
[...]
## end code ##

And @var should probably be used in the module's top level docstring in
the same manner.

2. In the argument to the tag for raises, how can I put a link
through to the exception?
Not 100% sure on this one; I would imagine that Epydoc would
automatically put those links in for you? Otherwise I don't believe L{}
can be used in the field name, only in the field text/body paragraph.
3. How would I go about marking up the property docs so that it knows
what the setter and getter methods are - it links through to the
methods but the docs arn't in there, they are in the fifth
argument to the property method (I can manually do this using
sections but is there a tag I can use?)

Like a previous poster said, can you show us an example? I don't quite
follow this one :)

HTH,
Jeff