#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 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?
> - 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.
> - 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?
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.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:27>
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.
