Daniele Varrazzo wrote:
> Paul Pogonyshev ha scritto:
> > Hi,
> >
> > How could I document such code?
> >
> > class AbstractFoo (object):
> > def bar (self):
> > # Not implemented.
> > raise NotImplementedError
> >
> > I would like something as standing out as "class method" in bar()
> > documentation, so that users really know they _must_ implement it
> > in a subclass for it to work.
>
> AFAIK there is nothing like what you ask for. Anyway it is something i
> already thought it could be useful. I can try to work a patch to add
> visual feedback for abstract methods.
>
> It may be a new tag for docstrings, which may warn the users that a
> function should be implemented by subclasses: i'd try to implement a tag
> like "@note" or "@attention", i.e. a tag taking a description as argument.
>
> How would you call such tag? "notimplemented"?
Maybe `abstract' or what you suggest. Maybe `unimplemented'.
> Differently from other tags, this one should not propagate down the
> inheritance tree: if bar() gets implemented but its documentation is not
> changed, the "notimplemented" tag should be dropped.
It should also probably put some notice into the method list, so that
information is available not only in longer method description. I think
it is not less important than information about method being static.
Probably should also put notice right below method name, e.g.:
foo (_class)
Class Method, Abstract
but it is not that important.
> I'd also try to parse for methods only composed by a "raise
> NotImplementedError" statement and automatically set them as
> "notimplemented".
Then also watch for methods with only
raise NotImplementedError (any-expression-here)
or
raise NotImplementedError, any-string
> Meanwhile i'd say to use the @newfield tag:
If you will add support for it into epydoc, I'll wait. I'm not in
hurry :)
> I'll try to create a new tag with the described characteristics. I'll
> make you know something in the next days.
Great, thanks. I'm subscribed here, so will notice if you post
anything to this list.
Paul
|
