#12891: Invite for contributing a doctest, if a user reads an untested function
or
method
------------------------------------------+---------------------------------
Reporter: SimonKing | Owner: was
Type: PLEASE CHANGE | Status: new
Priority: major | Milestone: sage-5.1
Component: user interface | Resolution:
Keywords: documentation untested | Work issues:
Report Upstream: N/A | Reviewers:
Authors: | Merged in:
Dependencies: | Stopgaps:
------------------------------------------+---------------------------------
Description changed by SimonKing:
Old description:
> On [http://groups.google.com/group/sage-
> devel/browse_thread/thread/aa60c0616ecdd1b6 sage-devel], Johan Grönqvist
> suggested to add a message when a function is called that has no doctest.
> The problem is that that would massively affect the performance.
>
> I suggested a modification of that idea: When the user reads the
> documentation of an untested function (or method) either in the notebook
> or the command line interface, s/he should be invited to contribute a
> test, such as
> {{{
> sage: def my_function(a,b):
> ....: """
> ....: some docs, but no test
> ....: """
> ....: return a+b
> ....:
> sage: my_function?
> Type: function
> Base Class: <type 'function'>
> String Form: <function my_function at 0x7309938>
> Namespace: Interactive
> Loaded File: /mnt/local/king/SAGE/stable/sage-5.0.beta13/devel/sage-
> main/<ipython console>
> Source File: /mnt/local/king/SAGE/stable/sage-5.0.beta13/devel/sage-
> main/<ipython console>
> Definition: my_function(a, b)
> Docstring:
> ####
> # my_function appears to be untested.
> # The Sage community would appreciate if someone (e.g., you)
> # added a test to the documentation.
> ####
> some docs, but no test
> }}}
>
> Reading the documentation is certainly not critical for performance. I
> thought it could be implemented in sage/misc/sagedoc.py or
> sage/misc/sageinspect.py. Unfortunately, this only holds for the ipython
> interface of Sage. The notebook seems to use stuff in
> sagenb/misc/support.py and sagenb/misc/sageinspect.py (which is an '''
> ''outdated'' copy''' of sage/misc/sageinspect.py!).
New description:
The aim of this ticket is to encourage users to (start to) contribute
doctests to Sage, so that we can more easily achieve the goal of full
doctest coverage.
On [http://groups.google.com/group/sage-
devel/browse_thread/thread/aa60c0616ecdd1b6 sage-devel], Johan Grönqvist
suggested to add a message when a function is called that has no doctest.
The problem is that that would massively affect the performance.
I suggested a modification of that idea: When the user reads the
documentation of an untested function (or method) either in the notebook
or the command line interface, s/he should be invited to contribute a
test, such as
{{{
sage: def my_function(a,b):
....: """
....: some docs, but no test
....: """
....: return a+b
....:
sage: my_function?
Type: function
Base Class: <type 'function'>
String Form: <function my_function at 0x7309938>
Namespace: Interactive
Loaded File: /mnt/local/king/SAGE/stable/sage-5.0.beta13/devel/sage-
main/<ipython console>
Source File: /mnt/local/king/SAGE/stable/sage-5.0.beta13/devel/sage-
main/<ipython console>
Definition: my_function(a, b)
Docstring:
####
# my_function appears to be untested.
# The Sage community would appreciate if someone (e.g., you)
# added a test to the documentation.
####
some docs, but no test
}}}
Or perhaps only add the message if the function's module starts with
'sage'.
Reading the documentation is certainly not critical for performance. I
thought it could be implemented in sage/misc/sagedoc.py or
sage/misc/sageinspect.py. Unfortunately, this only holds for the ipython
interface of Sage. The notebook seems to use stuff in
sagenb/misc/support.py and sagenb/misc/sageinspect.py (which is an '''
''outdated'' copy''' of sage/misc/sageinspect.py!).
--
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/12891#comment:1>
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.
