unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Paragraph styles in doc strings
@ 2016-05-09 14:57 Lars Ingebrigtsen
  2016-05-09 15:01 ` Dmitry Gutov
                   ` (3 more replies)
  0 siblings, 4 replies; 19+ messages in thread
From: Lars Ingebrigtsen @ 2016-05-09 14:57 UTC (permalink / raw)
  To: emacs-devel

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





^ permalink raw reply	[flat|nested] 19+ messages in thread
end of thread, other threads:[~2016-06-21  3:24 UTC | newest]

Thread overview: 19+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-05-09 14:57 Paragraph styles in doc strings Lars Ingebrigtsen
2016-05-09 15:01 ` Dmitry Gutov
2016-05-09 15:07   ` Kaushal Modi
2016-05-11  1:52     ` John Wiegley
2016-05-12 20:37       ` Lars Ingebrigtsen
2016-05-16 20:53         ` Stefan Monnier
2016-06-01 23:01           ` Clément Pit--Claudel
2016-06-02  1:18             ` Stefan Monnier
2016-06-20 19:11               ` Clément Pit--Claudel
2016-06-21  1:18                 ` Stefan Monnier
2016-06-21  3:24                   ` Clément Pit--Claudel
2016-05-18  6:05         ` John Wiegley
2016-05-09 16:05   ` Drew Adams
2016-05-09 15:10 ` Paul Eggert
2016-05-09 15:48   ` Marcin Borkowski
2016-05-09 16:12     ` Paul Eggert
2016-05-09 15:22 ` Andreas Schwab
2016-05-09 15:42   ` Lars Ingebrigtsen
2016-05-09 15:45 ` Marcin Borkowski

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).