On Wed, 17 May 2017, Kwankyu Lee wrote:
I am simply asking why we aren't writing a docstring as
"Return True if ...." instead of "Return ``True`` if ...".
This would be OK for me. Should it even be "Return true if ..."?
But now I will write a long story about short docstrings. Let's suppose we
have an is_* -function with a certificate option. See finite lattices
(lattices.py) for an example.
1) We have policy of using "certificate" instead of "certify". Also I
suppose that everybody wants certificate=False to be the default.
2) We have policy to start with one-sentence description that tells about
what is the main use for the function.
3) We have policy to start with "Return" instead of "Returns" (in
general "do that" instead of "does that").
4) We do not have policy about "the object" vs. "self"; for examples
"...if the lattice is" vs. "...if ``self`` is".
5) We do not have policy about "true", "True" or "``True``".
6) We do not have policy about writing
"Return True if the <object> is <property>."
"Return True if the <object> is <property> and False otherwise."
"Return True if the <object> is <property>, and False otherwise."
"Return whether the <object> is <property>."
"Test if the <object> is <property>."
7) We have policy to start longer description with assumptions of the
object, if there are any.
8) We do not(?) have policy of whether to end the INPUT section with dot.
Currently there is for example "- certificate -- (default: False) whether
to return a certificate if the lattice is not isoform".
9) Same applies(?) to OUTPUT section.
10) How should we format OUTPUT anyways? Now there is "- If
certificate=True return either (True, None) or (False, C), where C is a
non-isoform congruence as a sage.combinat.set_partition.SetPartition. If
certificate=False return True or False.", but OTOH see is_dismantlable()
on lattices.py.
11) Is there a rule for the place if SEEALSO-block?
12) Having lists of weaker and stronger properties is my idea. It can be
discussed too.
13) When should we use the format LatticePoset({1: [...]...}) in the
examples, and when LatticePoset(DiGraph('GTE3_#H'))?
14) What are good examples anyway?
At least these questions can be discussed, and this was only for a very
small and clearly defined function.
--
Jori Mäntysalo
