Paragraph styles in doc strings

[Lars Ingebrigtsen]

There seems to be three popular paragraph styles in Emacs doc strings.

Indentation:

-----
(directory-files DIRECTORY &optional FULL MATCH NOSORT)

Return a list of names of files in DIRECTORY.
There are three optional arguments:
If FULL is non-nil, return absolute file names.  Otherwise return names
 that are relative to the specified directory.
If MATCH is non-nil, mention only file names that match the regexp MATCH.
If NOSORT is non-nil, the list is not sorted--its order is unpredictable.
 Otherwise, the list returned is sorted with ‘string-lessp’.
 NOSORT is useful if you plan to sort the result yourself.
-----

Newline:

-----
(make-byte-code ARGLIST BYTE-CODE CONSTANTS DEPTH &optional DOCSTRING
INTERACTIVE-SPEC &rest ELEMENTS)

Create a byte-code object with specified arguments as elements.
The arguments should be the ARGLIST, bytecode-string BYTE-CODE, constant
vector CONSTANTS, maximum stack size DEPTH, (optional) DOCSTRING,
and (optional) INTERACTIVE-SPEC.
The first four arguments are required; at most six have any
significance.
The ARGLIST can be either like the one of ‘lambda’, in which case the arguments
will be dynamically bound before executing the byte code, or it can be an
integer of the form NNNNNNNRMMMMMMM where the 7bit MMMMMMM specifies the
minimum number of arguments, the 7-bit NNNNNNN specifies the maximum number
of arguments (ignoring &rest) and the R bit specifies whether there is a &rest
argument to catch the left-over arguments.  If such an integer is used, the
arguments will not be dynamically bound but will be instead pushed on the
stack before executing the byte-code.
-----

Empty line:

-----
(get-buffer-create BUFFER-OR-NAME)

Return the buffer specified by BUFFER-OR-NAME, creating a new one if needed.
If BUFFER-OR-NAME is a string and a live buffer with that name exists,
return that buffer.  If no such buffer exists, create a new buffer with
that name and return it.  If BUFFER-OR-NAME starts with a space, the new
buffer does not keep undo information.

If BUFFER-OR-NAME is a buffer instead of a string, return it as given,
even if it is dead.  The return value is never nil.
-----

Of these three, "newline" is probably the most used and "indentation" is
the least.

So my question is: Should we try to converge on one of these three
styles, and if so, which one?

I think the "newline" one is the worst one.  If the paragraph happens to
end on a line that's the normal length, it's impossible to see that the
paragraph ends there.  So it's naturally confusing.

The "indentation" one doesn't suffer from this confusion, but it's a
pain to write (which might be why so few doc strings use this style),
and I don't this the readability is as good as it should be.

So my favourite is definitely the "empty line" one.  It's easy to write
(just use `M-q' at will), and I think it's easy to read.  It does add
vertical space, so you get less information on the screen, but I think
it gains more in clarity what it loses in conciseness.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no