#9976: Decorated functions/methods have generic signature in documentation
--------------------------------+-------------------------------------------
Reporter: jsrn | Owner: jsrn
Type: enhancement | Status: needs_review
Priority: major | Milestone: sage-4.7
Component: documentation | Keywords: sphinx, documentation, cython
inspection
Author: jsrn, Simon King | Upstream: N/A
Reviewer: Simon King | Merged:
Work_issues: |
--------------------------------+-------------------------------------------
Comment(by SimonKing):
Replying to [comment:127 jhpalmieri]:
> There is a lot on this ticket, and I haven't read most of it. But here
is one comment nonetheless: suppose I have this in a Sage library file:
> {{{
> from sage.misc.cachefunc import CachedFunction
>
> def test1():
> "This is a docstring for test1"
> pass
>
> test2 = CachedFunction(test1)
>
> @CachedFunction
> def test3():
> "This is a docstring for test3"
> pass
> }}}
> Then if I import everything from this file, from the "sage:" prompt, I
get the right docstrings for the right functions. Great! On the other
hand, the function test3 is completely missing from the reference manual
Why do you think test3 is missing? The cached version of test3 has the
name test3, and when you do "from mymodule import test3" then you are
supposed to get the cached version of test 3, with the documentation
saying "This is a docstring for test3". If I am not mistaken, this was the
case even without our patches.
Concrete example, ''without'' our patches:
{{{
sage: sage.databases.cunningham_tables.cunningham_prime_factors?
Type: CachedFunction
Base Class: <class 'sage.misc.cachefunc.CachedFunction'>
String Form: Cached version of <function cunningham_prime_factors at
0x38e62a
8>
Namespace: Interactive
File: /mnt/local/king/SAGE/sage-4.6.2/local/lib/python2.6/site-
packages/sage/misc/cachefunc.py
Definition:
sage.databases.cunningham_tables.cunningham_prime_factors(self, *args,
**kwds)
Docstring:
List of all the prime numbers occuring in the so called Cunningham
table. They occur in the factorization of numbers of type b^n+1 or
b^n-1 with b in {2,3,5,6,7,10,11,12}. Data from
http://cage.ugent.be/~jdemeyer/cunningham/
Class Docstring:
Create a cached version of a function, which only recomputes values
it hasn't already computed. Synonyme: ``cached_function``
...
}}}
In other words, it does show you the documentation of the wrapped
function. In addition, it also shows you the documentation of
`CachedFunction`.
It seems that the Cunningham database was not included in the reference
manual, but it ''should'' show the documentation of the wrapped function,
not of the wrapper class.
However, as you see, without our patches you will not get the correct
argspec: It says
"sage.databases.cunningham_tables.cunningham_prime_factors(self, *args,
**kwds)", but should say
"sage.databases.cunningham_tables.cunningham_prime_factors()". It also
tells you that you find its definition in sage/misc/cachefunc.py, which is
of course wrong.
The main point of this ticket is to improve the issue with argspec.
Documentation as such worked before.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:129>
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.
