#10077: Improve doc about coding conventions
-------------------------------+--------------------------------------------
Reporter: jpflori | Owner: mvngu
Type: enhancement | Status: needs_review
Priority: trivial | Milestone: sage-4.6
Component: documentation | Keywords: documentation, coding convention
Author: Minh Van Nguyen | Upstream: N/A
Reviewer: | Merged:
Work_issues: |
-------------------------------+--------------------------------------------
Comment(by mvngu):
Replying to [comment:2 novoselt]:
> I a bit disagree with the interpretation of "TESTS" directive. I tend to
put there any tests that do not really help in illustrating the function.
For example, if there was a bug detected on some valid but long and
perhaps obscure input, I think that it should go to TESTS.
And also providing the corresponding ticket number (if available) of the
ticket for that bug.
[[BR]][[BR]]
> On the other hand, if some exceptions are not unusual, they may very
well be illustrated in EXAMPLES, e.g. solving an overdetermined system of
equations.
This depends on the specific case. But I agree with this comment of yours.
[[BR]][[BR]]
> Personally, I think that EXAMPLES are bits of code that show how to use
a function.
Nod.
[[BR]][[BR]]
> Bits of code that make sure that every branch of code got executed can
be much more numerous than necessary for illustration.
Nod. Such code can go in the TESTS block. If there are too many such
tests, create a sepatate test file, but don't include them in the
reference manual.
[[BR]][[BR]]
> What's the point of "notes" in lower case? Is it really necessary for
something or maybe it is possible to list only `.. NOTES::`?
I tend to encourage the use of the Sphinx directive for notes. That is,
use the lower-case ".. note::" or the upper-case version ".. NOTE::"
(choose one). But Sphinx doesn't recognize ".. notes::" nor ".. NOTES::"
(notice the "s" before the double colon). Both the
[http://sphinx.pocoo.org/rest.html#directives Sphinx] and the
[http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
ReST] documentation say that "notes" with an "s" is not supported.
[[BR]][[BR]]
See my [http://trac.sagemath.org/sage_trac/ticket/10078#comment:4 comment]
at #10078 for reasons why I encourage (but not say "must") the use of
upper-case versions of admonitions, etc.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/10077#comment:5>
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.
