docs: add docstring #567
docs: add docstring #567
Conversation
There was a problem hiding this comment.
Looks good, but I take this opportunity to be pedantic about style, generally following PEP257 and pydocstyle / ruff
| quadrature_kind: | ||
| What kind of quadrature to use. | ||
| A denser quadrature makes the result more accurate but takes longer to compute. | ||
| What options exists depend on the sample shape. |
There was a problem hiding this comment.
You can use a Literal as the type of quadrature_kind to tell the users which arguments are possible. As it stands, it is very difficult to find that out.
src/scippneutron/absorption/base.py
Outdated
| Parameters | ||
| ---------- | ||
| sample_shape: | ||
| the size and shape of the sample |
There was a problem hiding this comment.
Capitalization and punctuation are inconsistent here. Please make every entry in Parameters (and the return documentation) one or more sentences. I.e., begin with a capital letter and end with a period.
src/scippneutron/absorption/base.py
Outdated
| @@ -15,6 +15,33 @@ def compute_transmission_map( | |||
| detector_position: sc.Variable, | |||
| quadrature_kind: Any = 'medium', | |||
| ) -> sc.DataArray: | |||
| """ | |||
| Computes the fraction of neutrons transmitted through the sample | |||
| given that they scattered to the positions in the ``detector_positions`` array. | |||
There was a problem hiding this comment.
The first sentence of a docstring should only be a single line and it should be its own paragraph, i.e., separated by an empty line from the rest. (See also https://peps.python.org/pep-0257/#multi-line-docstrings) Sphinx rtelies on this and shows the first paragraph in summary tables. And there is little space there. So please split it up and write a concise summary plus an expanded explanation.
Typically, the summary uses imperative mood. But we don't do that consistently in Scipp.
Co-authored-by: Jan-Lukas Wynen <[email protected]>
Please be! |
No description provided.