#9976: Decorated functions/methods have generic signature in documentation
--------------------------------+-------------------------------------------
Reporter: jsrn | Owner: mvngu
Type: enhancement | Status: needs_work
Priority: major | Milestone: sage-4.7
Component: documentation | Keywords: sphinx, documentation, cython
inspection
Author: jsrn, Simon King | Upstream: N/A
Reviewer: | Merged:
Work_issues: |
--------------------------------+-------------------------------------------
Comment(by jsrn):
Replying to [comment:27 SimonKing]:
> Hi Johan,
>
> Replying to [comment:24 jsrn]:
> > - In sage_autodoc.py:820, we catch a TypeError which might be thrown
by sage_getargspec. However, as the comment on the following lines
indicates, this is because the old method inspect.getargspec(obj) throws
TypeErrors whenever obj is a class (as you demonstrated above). Is the
nested try-catch-clauses on those lines still sensible?
>
> Probably it isn't needed, but I think it doesn't hurt, does it?
I'll try to do some testing without it; if it causes problems, then we'll
leave it. Otherwise, I don't care much for confusing and rotting code ;-)
>
> > - You import _sage_getdoc_unformatted into sage_autodoc but isn't it
bad Python practice to import a method indicated to be private? Should we
just ignore this anyway?
>
> I don't know much about Python conventions. And actually it could be
that "sage_getdoc" is more appropriate for "sage_autodoc.py" anyway. So,
I'll try to change it.
>
> > - Shouldn't the entire sage_autodoc.py be changed to use the
sageinspect module instead of the python.inspect module? It seems a bit
haphazard to use one some places and the other elsewhere. If this was
never the intention of sageinspect, or if it would require a huge amount
of effort, then I'm perfectly ok with not doing this ;-)
>
> If I am not mistaken, the sageinspect module is intended to replace only
a part of the Python inspect module. And if you look into the patched
sage_autodoc.py, you will find that we only use the following auxiliary
methods from the inspect module
> {{{
> inspect.isbuiltin
> inspect.ismethoddescriptor
> inspect.isfunction
> inspect.isroutine
> inspect.ismethod
> inspect.formatargspec
> }}}
>
> The only "is*"-function in sageinspect is
"sage.misc.sageinspect.isclassinstance", and there is also no alternate
version of "formatargspec". So, I think it is just fine to use these bits
from the Python inspect module.
Sounds fine.
>
> > - In sageinspect.py: 677, you call an object's _sage_argspec_ method.
Is this an object attribute that you have invented or did I miss
something? In my original patch, I invented the "_sage_getargspec"
attribute for callables, which is not a method but a tuple property of the
object, following the same format that inspec.getargspec would return.
Shouldn't these two be merged to the same attribute, and wouldn't that
imply a simplification in your patch of sage_autodoc's format_args
functions? If they should indeed be different but it is something that you
invented, it should be documented in some comments somewhere.
>
> As I mentioned above, I don't know much about Python conventions. But I
thought it is considered bad practice to provide that type of data by
arguments?
Huh, why oh why? Ok, I never really read those conventions, but if you say
so ;-)
>
> Anyway, _sage_argspec_ is a ''method'', and it is not my invention, but
was used in sageinspect before. Other methods used are _sage_doc_,
_sage_src_ and _sage_src_lines_.
>
> So, actually it might be a good idea to change your patch so that it
uses the existing _sage_argspec_ method, rather than introducing a
_sage_getargspec attribute.
Definitely, if that is the way Sage does it elsewhere; I weren't aware of
that. I'll look into changing my patch; what kind of stuff does
_sage_argspec_ usually return?
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:29>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en.
