#17447: Clarify and complete documentation of function()
-------------------------+-------------------------------------------------
Reporter: | Owner:
schymans | Status: needs_work
Type: | Milestone: sage-6.5
enhancement | Resolution:
Priority: major | Merged in:
Component: | Reviewers: Ralf Stephan
documentation | Work issues:
Keywords: | Commit:
Authors: | 4585e74063e81a8c332a500d016e837069edf8eb
schymans | Stopgaps:
Report Upstream: N/A |
Branch: |
public/17447 |
Dependencies: |
-------------------------+-------------------------------------------------
Comment (by nbruin):
Replying to [comment:18 kcrisman]:
> Also, does the current branch actually "clarify and complete
documentation of function"? It looks like it mostly fixes doctests.
I think there are two things that are/were confusing:
- `function('f',x)` returns something that is not, according to our
definition, a function (e.g., it cannot be evaluated ("called") in a non-
ambiguous way and hence triggers a deprecation warning)).
- The top-level `function` makes a binding in the global namespace and
returns a value. The two were different.
With the proposed patch, `function('f',x)` is deprecated, so number 1 gets
eliminated and number 2 is less confusing because, while it still injects
something in the namespace, the value it returns is always the same as
what it injects.
When I read the documentation of
`sage.symbolic.function_factory.function`, I actually thought it described
what happens fairly correctly, and it has good examples. Hence I did not
feel the need to add to it. The top-level `function` documentation is
rather sparse, so that could use expansion. However, we do not want to
repeat ourselves, so perhaps it should just contain a clear pointer
(hyperlink?) to the documentation of
`sage.symbolic.function_factory.function`. I don't know how to do that, so
please go ahead and improve that bit. You are excellently qualified to
produce extensive and understandable documentation for the target audience
of these functions.
> Another change not doctested is
> {{{
> if is_SymbolicVariable(dvar):
> - raise ValueError("You have to declare dependent variable as a
function, eg. y=function('y',x)")
> + raise ValueError("You have to declare dependent variable as a
function evaluated at the independent variable, eg. y=function('y')(x)")
> }}}
> which I think happens twice.
These messages weren't doctested before either. If you feel the projects
benefits from such administrations, go ahead.
> I'm ''still'' not sure I even understand some of the subtle differences.
Are there occasions where the old behavior was "right" in the sense that
one wanted that returned, and have we shown how to get that object?
In my opinion: no. In all cases, `function('f')(x)` is much clearer and
not much longer than `function('f',x)`. There are *many* tickets and
questions about people getting tripped up by the fact that a function
called function doesn't return a function.
> What about the ask.sagemath question?
In my opinion, that's another thing to document. However, the confusion
about function not returning a function definitely contributed to the
confusion about how to use substitute_function.
--
Ticket URL: <http://trac.sagemath.org/ticket/17447#comment:19>
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 unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/d/optout.
