#9976: Decorated functions/methods have generic signature in documentation
-----------------------------------------------------+----------------------
Reporter: jsrn | Owner: jsrn
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: Simon King | Merged:
Work_issues: Cosmetical changes, indirect doctests |
-----------------------------------------------------+----------------------
Comment(by jsrn):
Replying to [comment:109 SimonKing]:
> Here are some comments on your new patch:
Thank you -- good comments; I'm still a rookie so thanks for the patience
;-)
>
> You should add your name to the author list both in
doc/common/sage_autodoc.py and sage/misc/decorators.py.
There were no authors' list in sage_autodoc, so I made one. Documentation
is not created for sage_autodoc.py (heh, recursive documentation), so I
guess that was the reason. Anyway, I'm always in doubt as to when a change
constitutes something that should be on the authors' list. In time those
lists will be terribly bloated, I guess :-S
>
> You demonstrate various underscore methods in your examples. While such
methods should be documented, such that a developer can easily find out
what needs to be implemented for obtaining a specific functionality, I
think it would be better to use the "official" methods that use the
underscore methods, such as sage.misc.sageinspect.sage_getsource or
...sage_getargspec. Simply mark them as indirect doctest.
I completely agree! I didn't know "#indirect doctest" but as far as I
could gather, it's used when doctesting a method/function without actually
calling that method/function. Since that not what we're doing here, is it
really necessary?
>
> I suggest to edit the new examples, so that the comments appear as
proper text. It should also mention the ticket number. Note that you can
use unformatted text by using double back ticks, and also note the
spelling correction below.Hence,
> {{{
> EXAMPLES:
>
> Demonstrate that ``_sage_src_`` and ``__doc__`` are retained from
the
> decorated function (see trac ticket #9976)::
>
> sage: def square(f):
> ... @sage_wraps(f)
> ... def new_f(x):
> ... return f(x)*f(x)
> ... return new_f
> }}}
> instead of
> {{{
> EXAMPLES::
>
> # Demonstrate the _sage_src_ and __doc__ are retained from the
> # decorated function
> sage: def square(f):
> ... @sage_wraps(f)
> ... def new_f(x):
> ... return f(x)*f(x)
> ... return new_f
> }}}
>
Yup, done (I think). It seems that decorators.py does not appear in the
reference manual; shouldn't that be changed (other ticket)? Do you know
how?
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:110>
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.
