From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Lars Ingebrigtsen Newsgroups: gmane.emacs.devel Subject: Paragraph styles in doc strings Date: Mon, 09 May 2016 16:57:07 +0200 Organization: Programmerer Ingebrigtsen Message-ID: <878tzjjn3w.fsf@gnus.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 8bit X-Trace: ger.gmane.org 1462806016 27682 80.91.229.3 (9 May 2016 15:00:16 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 9 May 2016 15:00:16 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon May 09 17:00:05 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1azmek-0000SM-JW for ged-emacs-devel@m.gmane.org; Mon, 09 May 2016 16:59:34 +0200 Original-Received: from localhost ([::1]:41758 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1azmek-0007OE-1L for ged-emacs-devel@m.gmane.org; Mon, 09 May 2016 10:59:34 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49008) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1azmeZ-00076u-Sd for emacs-devel@gnu.org; Mon, 09 May 2016 10:59:28 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1azmeU-0007Ez-IG for emacs-devel@gnu.org; Mon, 09 May 2016 10:59:22 -0400 Original-Received: from plane.gmane.org ([80.91.229.3]:55327) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1azmeU-0007EI-4d for emacs-devel@gnu.org; Mon, 09 May 2016 10:59:18 -0400 Original-Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1azmdw-00083i-IS for emacs-devel@gnu.org; Mon, 09 May 2016 16:58:44 +0200 Original-Received: from cm-84.215.1.64.getinternet.no ([84.215.1.64]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 09 May 2016 16:58:44 +0200 Original-Received: from larsi by cm-84.215.1.64.getinternet.no with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 09 May 2016 16:58:44 +0200 X-Injected-Via-Gmane: http://gmane.org/ Mail-Followup-To: emacs-devel@gnu.org Original-Lines: 77 Original-X-Complaints-To: usenet@ger.gmane.org X-Gmane-NNTP-Posting-Host: cm-84.215.1.64.getinternet.no Mail-Copies-To: never User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux) Cancel-Lock: sha1:k01DziSu3qwhjqsbXndSN/Lun94= X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 80.91.229.3 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:203712 Archived-At: 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