Thread: [Epydoc-devel] abstract functions
Brought to you by:
edloper
From: Paul P. <pog...@gm...> - 2007-01-03 22:46:34
|
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. Paul |
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 |
From: Paul P. <pog...@gm...> - 2007-01-08 20:16:01
|
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 |
From: Daniele V. <dan...@gm...> - 2007-01-09 10:41:18
|
> > How would you call such tag? "notimplemented"? > > Maybe `abstract' or what you suggest. Maybe `unimplemented'. abstract could be confused with "an article abstract" and probably would conflict with the matching reST tag. [...] > > 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 Nice: the exception argument would be used as field description. |