#10111: random_prime is badly documented.
-----------------------------+----------------------------------------------
Reporter: drkirkby | Owner: mvngu
Type: enhancement | Status: new
Priority: major | Milestone: sage-4.7
Component: documentation | Keywords:
Author: | Upstream: N/A
Reviewer: | Merged:
Work_issues: |
-----------------------------+----------------------------------------------
Changes (by drkirkby):
* cc: fwclarke, burcin (added)
Old description:
> The {{{random_prime()}}} function in Sage can take one, two or three
> arguments. But all the examples shown in the documentation or
> {{{random_prime}}} use only one argument. The more complex cases are not
> documented and not tested.
>
> See also
> http://groups.google.com/group/sage-
> devel/browse_thread/thread/6e8d6f28c915830d?hl=en
>
> These are the examples given.
>
> {{{
> sage: random_prime(100000)
> 88237
> sage: random_prime(2)
> 2
> }}}
>
> Although some with good Python knowledge may argue the behavior with 2 or
> 3 arguments is documented properly, I personally think it could be
> clearer.
>
> For example, I'm told:
> {{{
> random_prime(123,False)
> }}}
>
> would normally be written as
>
> {{{
> random_prime(123, proof=False)
> }}}
>
> It would be good with someone with decent Python knowledge to write some
> examples of using this function with 2 or 3 arguments.
>
> See also #10112, where it is shown that the function hangs for certain
> erroneous inputs.
New description:
The {{{random_prime()}}} function in Sage can take one, two or three
arguments. But all the examples shown in the documentation or
{{{random_prime}}} use only one argument. The more complex cases are not
documented and not tested.
See also
http://groups.google.com/group/sage-
devel/browse_thread/thread/6e8d6f28c915830d?hl=en
These are the examples given.
{{{
sage: random_prime(100000)
88237
sage: random_prime(2)
2
}}}
Although some with good Python knowledge may argue the behavior with 2 or
3 arguments is documented properly, I personally think it could be
clearer.
For example, I'm told:
{{{
random_prime(123,False)
}}}
would normally be written as
{{{
random_prime(123, proof=False)
}}}
It would be good with someone with decent Python knowledge to write some
examples of using this function with 2 or 3 arguments.
See also #10112, where it is shown that the function hangs for certain
erroneous inputs.
It should also be noted that the error message "''n must be greater than
lbound ''" is incorrect, and should be changed to "''n must be at least
lbound''"
--
Comment:
Since there appears to be some disagreement about the code changes on
#10112, if those can't be resolved soon, I suggest we just change the
documentation on this ticket. The 3 changes needed are:
* The error message "''n must be greater than lbound ''" is incorrect,
and should be changed to "''n must be at least lbound''"
* The example {{{random_prime(200, lbound=100)}}} is added
* The example {{{random_prime(200, proof=False, lbound=100)}}} is added.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/10111#comment:3>
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.
