#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 |
-----------------------------------------------------+----------------------
Changes (by SimonKing):
* status: needs_review => needs_work
* reviewer: => Simon King
* work_issues: => Cosmetical changes, indirect doctests
Comment:
Here are some comments on your new patch:
You should add your name to the author list both in
doc/common/sage_autodoc.py and sage/misc/decorators.py.
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 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
}}}
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:109>
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.
