Re: [Epydoc-devel] abstract functions

[Daniele V. <dan...@gm...>]

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"?

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.

I'd also try to parse for methods only composed by a "raise 
NotImplementedError" statement and automatically set them as 
"notimplemented".

Meanwhile i'd say to use the @newfield tag:

     class AbstractFoo (object):
         """Testing not implemented

         @newfield notimplemented: Not implemented
         """
         def bar (self):
             """Wicket the wocket

             @notimplemented: Subclasses must know how to bar
             """
             raise NotImplementedError

     class Foo(AbstractFoo):
         def bar(self):
             return 10

which yields a message explicit enough, though not shown in the class 
summary but only in the method details.

Curiously, the "Not implemented" message doesn't appear in the "Foo" 
documentation! It should be a newfield bug, i don't think my laptop is 
getting smarter than me. Anyway i am running epydoc 3 from a svn trunk 
checkout of some week ago, so i don't know what the current behavior 
really is.

I'll try to create a new tag with the described characteristics. I'll 
make you know something in the next days.

Cheers,

Daniele