#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 jsrn):
I'm running doctests now. I've read through the code, and it looks good
with many good comments and tests.
While we are waiting for the results, I do have one thing, though: I'm not
really fond of the doc-tests that depend on completely unrelated code,
like the ones demonstrating error in partition_algebra. It seems to incur
a large penalty for developers in the long run, as any change in existing
code will break doctests in completely unrelated modules.
Sure, most of these errors will be easy to fix, but then the doctest might
become invalid (if e.g. partition_algebra moved away from using
functools.partial), and the later developer would have to decide between
1) fixing the doctest and keeping it, even though it no longer serves its
purpose, 2) remove the doctest, or 3) rewrite the doctest to use a
different module or doctest-created objects. 1) and 2) would result in the
error no longer being exercised, defeating the purpose of having this
(non-educating) doctests lying around. 3) would be a huge and unwanted
burden for the new developer to lift, and he might not have the
prerequisites to do it.
One might disagree with this of course. So, is this something that you
have seen many places in Sage (so that it is completely
acceptable/encouraged doctesting)? Or is it because this particular
doctest is impossible to write using dynamic objects (I haven't really yet
fully understood which of the functions work on dynamic objects and which
only on file-read ones)? Or is there a third reason?
Thanks for the green light on mine, by the way.
Cheers,
Johan
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:164>
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.
