#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):
I have some other thoughts about our patches. The line numbers below are
after patching with both patches:
- 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?
- 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?
- 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 ;-)
- 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.
Cheers,
Johan
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:24>
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.
