Re: [Epydoc-devel] abstract functions

[Paul P. <pog...@gm...>]

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