#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: |
--------------------------------+-------------------------------------------
Comment(by jsrn):
This is horrible! What were they thinking?!...
Ok, in this case I think it actually would be best to always return the
argspec of the underlying function. It is bad to be forced to erase the
default arguments from the argspec, even though they can still be set by
name. There I would prefer these args to be in the documentation but then
the doc text explained more in depth how it could be used. It is also
easier to work around, once the code has been written in one way (and the
code author suddenly discovers this documentation issue), I think.
>> We might even consider giving a warning in cases where this is not
done (as it is an error to write Sage code which doesn't document
properly, or something). Thinking about it, I don't think this solution is
very difficult to implement.
>
> Like a deprecation warning? I think that would be not so good. If people
have the freedom to use functools.partial, then we should cope with it.
What I meant is to produce a warning in sage_autodoc or sageinspect.sage_*
if we come upon a function with this behaviour -- but only on the module-
level which is to be documented.
The rationale would be that functools.partial (in cases such as these)
very much violates "principle of least surprise" and is therefore bad for
the end-user. Code authors should be allowed to do whatever internally in
the modules, but for the end-user, we wish them to have a straight-
forward, Pythonic experience with Sage; suddenly having functions where
arguments can _only_ be given by name and introspection and documentation
strings is non-standard, lacking or broken is surprising and confusing.
Even more so in a language such as Python, where we expect "one way to do
it" and relatively well-behaved foundational syntax rules of the language
(where, on the other hand, stuff like this would be practically mandatory
in a Perl program ;-) ).
Of course, we should never introduce such things without consulting sage-
devel first.
Cheers
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:160>
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.
