Re: [Epydoc-devel] how to document methods imported from other modules?

[Edward L. <ed...@gr...>]

On Jun 27, 2007, at 8:40 PM, Paul Pogonyshev wrote:
> However, there appears to be another problem...  If I document the
> attached module, I get
>
> 	Method Details
> 	object_context_manager(*args, **kwds)
> 	
> Instead of object_context_manager(self), which would be more logical.
> Is that a known problem?

Unfortunately, the way contextmanager is defined, there's no good way  
to introspect the arguments that are given to the wrapped function.   
And without knowing what the decorator does, the source code parsing  
can't just assume that the argument list stays the same.  The easiest  
solution here is to add a line to the docstring, giving the correct  
signature.  (The same thing needs to be done for builtin functions,  
since their signature can't be introspected.)  So the following  
should do what you want:

   @contextmanager
   def object_context_manager(self):
       """
       object_context_manager(self)

       description...
       """
       ...

In the long term, it might be good to add contextmanager to the list  
of decorators that epydoc's source code parser has explicit knowledge  
about.  (Currently this list includes classmethod and staticmethod.)

-Edward