Re: [Epydoc-devel] abstract functions
Brought to you by:
edloper
From: Daniele V. <dan...@gm...> - 2007-01-08 10:05:29
|
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 |