Re: [Epydoc-devel] abstract functions
Brought to you by:
edloper
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 |