#19041: Better description of docstrings in the developer guide
-------------------------------------+-------------------------------------
Reporter: vdelecroix | Owner:
Type: enhancement | Status: needs_review
Priority: major | Milestone: sage-6.9
Component: documentation | Resolution:
Keywords: | Merged in:
Authors: Vincent | Reviewers: Nathann Cohen
Delecroix, Jori Mäntysalo | Work issues:
Report Upstream: N/A | Commit:
Branch: | d01d36d74b80e44b6676c82b5ae02247e3200e30
u/jmantysalo/19041 | Stopgaps:
Dependencies: |
-------------------------------------+-------------------------------------
Comment (by dkrenn):
Replying to [comment:24 jmantysalo]:
> First of all, I am very glad to see someone interested in making better
documentation, even when it comes to small things!
:)
> Should we have even manual for documenting "common special types" of
functions? "If the function has no arguments and only returns `True` or
`False`, then do like this: - -"?
You mean like short examples for some special cases...sounds like a good
idea.
> What do you think about `hamiltonian_cycle()` and `is_hamiltonian()` on
generic graphs vs. `dimension()` and it's `certificate`-option on posets?
Those seems to be OK, but in general: when to have "factor" and when
"is_prime(certificate=True)"?
This is not that easy; I can see plus-points for both sides: Using such a
flag means to have only *one* function for the desired functionality,
which is usually a good thing. On the other hand, getting different a
output type depending the input is sometimes not seen as good practice.
In particular, the `certificate`-option does not give back the dimension,
but only the certificate, which is kind of weird, since I would expect a
method called `dimension` to return a dimension in any case...
--
Ticket URL: <http://trac.sagemath.org/ticket/19041#comment:25>
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.
