Download Sage Developer`s Guide

Sage Developer’s Guide, Release 6.9
output of git blame). Nevertheless, it is sometimes useful to have a very rough overview over the history, especially
if a lot of people have been working on that source file.
All code included with Sage must be licensed under the GPLv2+ or a compatible, that is, less restrictive license (e.g.
the BSD license).
3.1.5 Documentation Strings
The docstring of a function: content
Every function must have a docstring that includes the following information. You can use the existing functions of
Sage as templates.
• A one-sentence description of the function.
It must be followed by a blank line and end in a period. It describes the function or method’s effect as a command
(“Do this”, “Return that”), not as a description like “Returns the pathname ...”.
• An INPUT and an OUTPUT block describing the input/output of the function. This is not optional.
The INPUT block describes all arguments that the function accepts, and the OUTPUT section describes its
expected output.
1. The type names should be descriptive, but do not have to represent the exact Sage/Python types. For
example, use “integer” for anything that behaves like an integer, rather than int.
2. Mention the default values of the input arguments when applicable.
Example:
INPUT:
- ‘‘p‘‘ -- (default: 2) a positive prime integer.
OUTPUT:
A 5-tuple consisting of integers in this order:
1.
2.
3.
4.
5.
the smallest primitive root modulo p
the smallest prime primitive root modulo p
the largest primitive root modulo p
the largest prime primitive root modulo p
total number of prime primitive roots modulo p
You can start the OUTPUT block with a dash if you prefer:
OUTPUT:
- The plaintext resulting from decrypting the ciphertext ‘‘C‘‘
using the Blum-Goldwasser decryption algorithm.
• An EXAMPLES block for examples. This is not optional.
These examples are used both for:
1. Documentation
2. Automatic testing before each release.
They should have good coverage of the functionality in question.
44
Chapter 3. Writing Code for Sage