#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 SimonKing):
Replying to [comment:110 jsrn]:
> ...
> > 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?
"#indirect doctest" makes the sage coverage script happy. Namely, if you
do "sage -coverage" on some file, it will complain if any function or
method appears to not being tested in its doc string. Hence, it will
complain if in the `__str__` method of `Foo` you just have `sage: print
Foo`, because there is no `__str__` visible. But when you do `sage: print
Foo # indirect doctest`, then you assert that the invisible method ''is''
actually tested.
Note that `#indirect doctest` does ''not'' influence how the doctest is
executed. It really is just for the coverage script.
And yes, I do think that having an indirect test is necessary, since what
we want is to enable `sage_getsource` and `sage_getargspec` -- there is no
point in demonstrating that a certain object has an attribute
`_sage_doc_`, because that is not what is supposed to be called by the
user. Mind that the tests in the documentation are, at the same time,
examples.
> 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?
Probably it should be a different ticket.
How to add it:
There are some hand-written `.rst` files in doc/en/reference/. Probably
you want to edit `misc.rst`, and insert the line
{{{
sage/misc/decorators
}}}
right before `sage/misc/cachefunc`. I guess that would be a good place,
because `cachefunc` provides decorators (even though they do not inherit
from the stuff in `decorators.py`).
And that should already be it - after `sage -docbuild reference html`, it
should be there.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:112>
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.
