djcb/mu — pull request #89 by tarsius (2012-11-10 13:05:29+00:00)
Title: improve doc-strings

I should be working on something completely unrelated instead... but it's more difficult and I ended up procrastinating and creating this patch :-) I hope these efforts are appreciated.

The first sentence should summarize the variable's or function's
purpose and it should fit on the first line. Change existing
doc-string by:

* Move first sentence onto first line even if that makes it _a bit_
long.
* Move additional notes out of first sentence and add them later,
possibly as complete sentences.
* If I am uncertain whether doing the above would alter the meaning,
_don't_ do it.
* If fitting the initial sentence on the first line would require a
complete rewrite of the doc-string _don't_ do so unless it is very
easy to do.
* Remove indentation from second and later lines if it is there to
align them with the first in the source code, instead of in
`describe-*' output.
* Make "pullet point" lists a bit more consistent.

Obviously this does not fix all problems but it's a start.