Charles Choi has been writing a lot of Elisp lately and being a scrupulous developer, is careful to write informative and useful docstrings. Being conscientious, he’s careful to check the formatting of his docstrings by calling describe-function. That sounds simple enough but, as Choi, says, it’s actually a pain involving several steps and moving around in the text of the function.
Of course, being a programmer, Choi decided to automate the process. That’s a win because it makes it easier to (repeatedly) check the docstring resulting in better documentation for the end user.
Another issue that Choi addresses is the number spaces at the end of a sentence. That, of course, is a minefield and whatever you do is sure to offend someone. But a good case can be made that since docstrings are almost always displayed in a monospaced font, there should be two spaces at the end of a sentence.
There are some problems though. Fill-paragraph won’t enforce the value of sentence-end-double-space if sentences end with a single space. As usual, Emacs has us covered. Instead of just calling fill-paragraph you can first call repunctuate-sentences. That will add two spaces after each sentence, which is just what you want in these circumstances. Take a look at Choi’s post for the details.
Docstrings seem like a small thing but done right, they can be very useful. Choi’s post demonstrates some ways to make writing them a bit easier.