Block Docstring Styleguide
Ce contenu n’est pas encore disponible dans votre langue.
Welcome to the Block Docstring Styleguide to Flojoy Blocks.
Our styleguide is based on the NumPy Docstring Styleguide, which is a widely used styleguide for Python docstrings. If you are already familiar with it, then you are good to go. If not, we recommend you to give the following sections a quick read :)
The docstring consists of a number of sections separated by headings. Each heading should be underlined in hyphens, and the section ordering should be consistent with the description below.
1. Short summary
A one-line summary that does not use variable names or the function name, e.g.
Note that having a good short summary is very important since it will be used for SEO.
2. Extended Summary
A few sentences giving an extended description. This section should be used to clarify functionality, not to discuss implementation detail or background theory. You may refer to the parameters and the function name, but parameter descriptions still belong in the Parameters section.
Description of the function arguments, keywords and their respective types.
If it is not necessary to specify a keyword argument, use optional:
If there is a default value, you can specify it like this:
Explanation of the returned values and their types. Similar to the Parameters section, except the name of each return value is optional. The type of each return value is always required:
Note: also make sure to enclose variables in single backticks.
Here we go, you have successfully written a Flojoy Block docstring! 🎉
(This is currently a small subset of NumPy’s Docstring Styleguide, more docstring features such as Raises, Notes, etc. will be support in the future)
Need help with docstring formatting? Join our Discord community and we will help you out!