From the docstring of check_imperative_mood itself: “””D401: First line should be in imperative mood: ‘Do’, not ‘Does’. [Docstring] prescribes the function or method’s effect as a command: (“Do this”, “Return that”), not as a description; e.g. don’t write “Returns the pathname …”. (We’ll ignore the irony that this docstring itself would fail the test.)
If you’re using Emacs, grab clojure-mode.el from technomancy’s Github, which differs from the one in ELPA (I don’t know why, both claim to be version 1.11.5, maybe someone can comment on that?) but includes clojure-fill-docstring which will format docstrings with nice indentation and linewrapping, bound by default to C-c M-q. It will take this: (defn … Read more
I agree with “Anything that you can’t tell from the method’s signature”. It might also mean to explain what a method/function returns. You might also want to use Sphinx (and reStructuredText syntax) for documentation purposes inside your docstrings. That way you can include this in your documentation easily. For an example check out e.g. repoze.bfg … Read more
From the PEP8 Style Guide: PEP 257 describes good docstring conventions. Note that most importantly, the “”” that ends a multiline docstring should be on a line by itself, e.g.: “””Return a foobang Optional plotz says to frobnicate the bizbaz first. “”” For one liner docstrings, it’s okay to keep the closing “”” on the … Read more
In looking for an answer to a related question, I managed to find the answer to this one. The trim algorithm is implemented in inspect.cleandoc, of all places.
No. They are the same. The only difference is that the first one can contain a sequence of three unescaped double quotes, while the second can contain a sequence of three unescaped single quotes. (In other words, because the delimiters are different, there is a slight difference in what characters you can use inside them.) … Read more
From the Sphinx documentation: The default role (`content`) has no special meaning by default. You are free to use it for anything you like, e.g. variable names; use the default_role config value to set it to a known role. As a matter of personal preference, when writing Python docstrings, I use interpreted text (single backquotes) … Read more
When you write this function bar (foo) { return foo + foo; } If you place your cursor in the line just above function and you write /** when you push « Enter » you’ll be obtain this: /** * [bar description] * @param {[type]} foo Utilizing docstrings * @return {[type]} Utilizing docstrings */ function … Read more
VS Code renders markdown fine in mouse hovers – but doesn’t render standard docstring formats well The VS Code Python extension will use markdown that you put into a docstring for intellisense mouse hover information, but this doesn’t really meet any of the commonly accepted/used docstring formats for Python. It doesn’t properly layout any of … Read more
The other answers are great. But I thought I (the OP) ought to share what I do these days (a year or two after the question). I use Sphinx and its Markdown extension. Do the following: TL;DR: See Gist snippet. Sphinx-markdown-builder You need sphinx-markdown-builder python module. pip install sphinx sphinx-markdown-builder; Run Sphinx Not the autodoc, … Read more