Devel manual about docstrings

[jmantysalo]

This patch will slightly modify instructions for docstrings.

I would like to have even more pre-specified formats for some classes of functions. For example should Boolean-valued is_something() function be "Return True if...", "Test whether" or something else? Also we have an arbitrary decision to use algorithm= instead of implementation=, method= etc.

But as a first part, what you think about these changes?

[jmantysalo]

Hmm... There are already a "What doctests should test" -part, so at least part of this patch is duplicate.

---

New commits:

​ff65397

Devel manual: docstring writing

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​cb7c34c

Minor addition.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​49d57c8

Less duplication.

[jmantysalo]

No comments got.

Anyways, this now encourages slightly more to use TESTS block. Also I documented some arbitrary decisions made.

[jdemeyer]

1. The example of a TESTS block is badly indented (it was already badly indented by 3 spaces only).

2. I don't like advice of the form Do not use ... Be positive, say only what should be used.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​f61ed30

Minor changes.

[jmantysalo]

Replying to jdemeyer:

1. The example of a TESTS block is badly indented (it was already badly indented by 3 spaces only).

There were tabs. Corrected.

2. I don't like advice of the form Do not use ... Be positive, say only what should be used.

How about this "instead of" -formulation?

[jhpalmieri]

There is still one more tab. Could you also make this grammatical fix:

src/doc/en/developer/coding_basics.rst

@@ -283 +283 @@
    They should have good coverage of the functionality in question.
 
 -  A **SEEALSO** block (highly recommended) with links to related parts of
-   Sage. This helps users find the features that interests them and discover
+   Sage. This helps users find the features that interest them and discover
    the new ones. ::
 
        .. SEEALSO::

[jdemeyer]

Replying to jmantysalo:

How about this "instead of" -formulation?

Why not simply say "Use X"?

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​1b06af9

Reviewers comments.

[jmantysalo]

Replying to jhpalmieri:

There is still one more tab. Could you also make this grammatical fix:

Arghs, Emacs. Tab removed and fix applied.

Replying to jdemeyer:

How about this "instead of" -formulation?

Why not simply say "Use X"?

Sohehow "Use algorithm if there are several algorithms or backend programs to select from." sounds odd to me. It left me wondering what else I could use or what is the meaning of this sentence. Compare to "- - describes the function or method's effect as a command - - not as a description - -"

But as you wish, this is now changed too.

[jdemeyer]

I was thinking that you could document a few standard keywords in the same way:

• algorithm: choose between various implementation (with None meaning a sensible default, which could depend on installed optional packages).

• proof: is this is True, require a mathematically proven computation. With False, a probabilistic algorithm may be used.

• check: do some additional checks to verify the input parameters. This should not otherwise influence the functioning of the code (if code works with check=True, it should also work with check=False).

• coerce: convert the input parameters to a suitable parent. This is typically used in constructors. You can call a method with coerce=False to skip some checks if the parent is known to be correct.

• ...

[jmantysalo]

Replying to jdemeyer:

I was thinking that you could document a few standard keywords in the same way:

This is exactly what I hope to have in this list; and for example inplace should be added. But I still think that "Do not use"-list could be added; it will make this more explicit. An alternative for inplace with default False could be for example return_copy with default True, and that could be explained.

Has there been or suggested some other parameter name for coerce?

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​edb1e67

Additions to keywords.

[jdemeyer]

Replying to jmantysalo:

But I still think that "Do not use"-list could be added; it will make this more explicit.

As a separate list, it would already make more sense to me. That wouldn't clutter the original "keywords to use" list.

Has there been or suggested some other parameter name for coerce?

Not that I know, at least coerce is used consistently for this. But I guess that convert would be a better name.

[jmantysalo]

Replying to jdemeyer:

Replying to jmantysalo:

But I still think that "Do not use"-list could be added; it will make this more explicit.

As a separate list, it would already make more sense to me. That wouldn't clutter the original "keywords to use" list.

Tried, but found no good way to express this as separate list.

Should we go with this patch?

[jdemeyer]

Here is a proposal: replace

* Function parameter names:

by

* Common function keyword arguments:

  This is a list of some keyword arguments that many functions and methods take.
  For consistency, you should use the keywords from the list below with the meaning
  as explained here. Do not use a different keyword with the same meaning
  (for example, do not use ``method``; use ``algorithm`` instead).

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​8e02729

Explanation of common keywords.

[jmantysalo]

Replying to jdemeyer:

Here is a proposal: - -

A good proposal!

Now I think I am happy with this. I am compiling and hoping that Sphinx is also happy. Put to needs_review to wait for that.

[jmantysalo]

Compiled.

[mantepse]

Some decisions are arbitrary, but common convention makes the program
to look polished and professional.

should be

Some decisions are arbitrary, but common convention make the program
look more polished and professional.

Actually, I'd prefer

Some decisions are arbitrary, but common convention make life easier.

---

New commits:

​24e3ab9

Fix doc indentation

[mantepse]

Also, I think it is conventional to start in lower case after a colon.

[jmantysalo]

Replying to mantepse:

common convention make life easier.

Good and short, changed.

Replying to mantepse:

Also, I think it is conventional to start in lower case after a colon.

I trust you on this.

(Finnish has clear rule for this: use lowercase if and only if the part before the colon refers to one clause only, and uppercase otherwise.)

---

New commits:

​c446203

Still more fine tuning.

[mantepse]

Sorry, I missed a plural "s", it should be

Some decisions are arbitrary, but common conventions make life easier.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​74d9bdf

Add 's'.

[jmantysalo]

Replying to mantepse:

Sorry, I missed a plural "s", it should be

Some decisions are arbitrary, but common conventions make life easier.

's' added.

[tscrim]

Replying to mantepse:

Also, I think it is conventional to start in lower case after a colon.

That can be capitalized or not because the part after the colon could be a complete separate sentence. However, I feel it is better to not have it capitalized because it is being used as an explanatory clause.

[vbraun]

merge conflict

[git]

Branch pushed to git repo; I updated commit sha1. Last 10 new commits:

​f5a6aa3	Minor addition.
​0292b50	Less duplication.
​86e42a6	Minor changes.
​fe4818a	Reviewers comments.
​e5723d8	Additions to keywords.
​85385f5	Explanation of common keywords.
​5f007b0	Fix doc indentation
​b1e83b1	Still more fine tuning.
​d6e0d40	Add 's'.
​47df1ea	Merge branch 'u/jmantysalo/devel-manual' of trac.sagemath.org:sage into t/21646/devel-manual

[jmantysalo]

New try.

[jdemeyer]

Conflicts with 7.5.beta0

[git]

Branch pushed to git repo; I updated commit sha1. Last 10 new commits:

​e53d89b	Fix doc indentation
​6541f18	Still more fine tuning.
​819a989	Add 's'.
​5a7fda6	Devel manual: docstring writing
​a53ff2a	Minor addition.
​546dd66	Less duplication.
​d4254a4	Minor changes.
​b96d03d	Reviewers comments.
​8297b5b	Additions to keywords.
​f4818f0	Rebase to 7.5beta0

[jmantysalo]

Another try.