Paragraph styles in doc strings

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

Re: Paragraph styles in doc strings

[Dmitry Gutov]

On 05/09/2016 05:57 PM, Lars Ingebrigtsen wrote:

> So my favourite is definitely the "empty line" one.

+1

Re: Paragraph styles in doc strings

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 280 bytes --]

On Mon, May 9, 2016 at 11:03 AM Dmitry Gutov <dgutov@yandex.ru> wrote:

> On 05/09/2016 05:57 PM, Lars Ingebrigtsen wrote:
>
> > So my favourite is definitely the "empty line" one.
>
> +1
>

I like that style too for clarity; I used that in my emacs config.
-- 

-- 
Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 612 bytes --]

Re: Paragraph styles in doc strings

[Paul Eggert]

On 05/09/2016 07:57 AM, Lars Ingebrigtsen wrote:
> my favourite is definitely the "empty line" one.

Agreed. The other, more-compact styles had their plusses long ago, when 
we had to worry more about small (24x80 text) displays, but these 
plusses are less important now.

On a graphical display it might be nice if Emacs used a half-line to 
display empty lines, instead of using a full line, so as to waste less 
screen real estate while still making the *Help* buffer clear. This idea 
might be useful for *Info* and other buffers too.

Re: Paragraph styles in doc strings

[Andreas Schwab]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> 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.
> -----

This isn't a paragraph style, but a list style, only without bullet
points or numbering.  In a typeset document there wouldn't be extra
space between the items.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

Re: Paragraph styles in doc strings

[Lars Ingebrigtsen]

Andreas Schwab <schwab@suse.de> writes:

> This isn't a paragraph style, but a list style, only without bullet
> points or numbering.  In a typeset document there wouldn't be extra
> space between the items.

Well, it's used as a paragraph style here and there...  Here both also
both with and without with the "blank line" style.  :-)

-----
(interactive &optional ARG-DESCRIPTOR)

Specify a way of parsing arguments for interactive use of a function.
For example, write
 (defun foo (arg buf) "Doc string" (interactive "P\nbbuffer: ") .... )
 to make ARG be the raw prefix argument, and set BUF to an existing buffer,
 when ‘foo’ is called as a command.

The "call" to ‘interactive’ is actually a declaration rather than a
 function; it tells ‘call-interactively’ how to read arguments to pass
 to the function.  When actually called, ‘interactive’ just returns
 nil.

Usually the argument of ‘interactive’ is a string containing a code
 letter followed optionally by a prompt.  (Some code letters do not
 use I/O to get the argument and do not use prompts.)  To pass several
 arguments to the command, concatenate the individual strings,
 separating them by newline characters.

Prompts are passed to ‘format’, and may use % escapes to print the
 arguments that have already been read.
If the argument is not a string, it is evaluated to get a list of
 arguments to pass to the command.
Just ‘(interactive)’ means pass no arguments to the command when
 calling interactively.


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

Re: Paragraph styles in doc strings

[Marcin Borkowski]

On 2016-05-09, at 16:57, Lars Ingebrigtsen <larsi@gnus.org> wrote:

> 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.

+1

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: Paragraph styles in doc strings

[Marcin Borkowski]

On 2016-05-09, at 17:10, Paul Eggert <eggert@cs.ucla.edu> wrote:

> On a graphical display it might be nice if Emacs used a half-line to 
> display empty lines, instead of using a full line, so as to waste less 
> screen real estate while still making the *Help* buffer clear. This idea 
> might be useful for *Info* and other buffers too.

Nice idea.  Would setting a font to a smaller one on empty lines do the
trick?

It could be even made into a simple minor mode (perhaps a global one?).
Might be very useful for fitting more code on the screen, especially in
languages whose culture prefers lots of whitespace.

I'd gladly volunteer to write such a mode, if there is any interest.

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

RE: Paragraph styles in doc strings

[Drew Adams]

> So my favourite is definitely the "empty line" one.

+1

Re: Paragraph styles in doc strings

[Paul Eggert]

On 05/09/2016 08:48 AM, Marcin Borkowski wrote:
> Would setting a font to a smaller one on empty lines do the
> trick?

I assume so, but I haven't investigated.

Re: Paragraph styles in doc strings

[John Wiegley]

[-- Attachment #1: Type: text/plain, Size: 523 bytes --]

>>>>> Kaushal Modi <kaushal.modi@gmail.com> writes:

> On Mon, May 9, 2016 at 11:03 AM Dmitry Gutov <dgutov@yandex.ru> wrote:
>> On 05/09/2016 05:57 PM, Lars Ingebrigtsen wrote:
>> 
>> > So my favourite is definitely the "empty line" one.
>> 
>> +1
>> 

> I like that style too for clarity; I used that in my emacs config.

Same here.  +1 for empty line.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 629 bytes --]

Re: Paragraph styles in doc strings

[Lars Ingebrigtsen]

John Wiegley <jwiegley@gmail.com> writes:

>>>>>> Kaushal Modi <kaushal.modi@gmail.com> writes:
>
>> On Mon, May 9, 2016 at 11:03 AM Dmitry Gutov <dgutov@yandex.ru> wrote:
>>> On 05/09/2016 05:57 PM, Lars Ingebrigtsen wrote:
>>> 
>>> > So my favourite is definitely the "empty line" one.
>>> 
>>> +1
>>> 
>
>> I like that style too for clarity; I used that in my emacs config.
>
> Same here.  +1 for empty line.

Unless I've missed something, I think that means that everybody who's
weighed in here is in favour of the "empty line" style.  I think that
means that we should, perhaps, whenever we're doing doc fix ups, try to
reformat doc strings that do not adhere to this style.

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

Re: Paragraph styles in doc strings

[Stefan Monnier]

> Unless I've missed something, I think that means that everybody who's
> weighed in here is in favour of the "empty line" style.

FWIW, I like to keep the vertical space usage to a minimum, so I often
prefer to avoid the empty lines (and use the "Newline" style instead).

If we ever want to refill docstrings automatically (ideally when
displaying them), then we'll need some stronger hint than a newline.
So I guess an empty line is not a bad idea, but I would indeed welcome
some font-lock hack that make those empty lines shorter.


        Stefan

Re: Paragraph styles in doc strings

[John Wiegley]

>>>>> Lars Ingebrigtsen <larsi@gnus.org> writes:

> Unless I've missed something, I think that means that everybody who's
> weighed in here is in favour of the "empty line" style. I think that means
> that we should, perhaps, whenever we're doing doc fix ups, try to reformat
> doc strings that do not adhere to this style.

Sure, but there's no reason to be aggressive about it. The content is the
really important thing.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Paragraph styles in doc strings

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 1296 bytes --]

On 2016-05-16 16:53, Stefan Monnier wrote:
> If we ever want to refill docstrings automatically (ideally when
> displaying them), then we'll need some stronger hint than a newline.
> So I guess an empty line is not a bad idea, but I would indeed welcome
> some font-lock hack that make those empty lines shorter.

I'm not sure font-lock will work nicely for this. Blank lines are a multi-line pattern.

On the other hand, this seems to work OK:

(defvar help-blank-line-height 0.5)
(defvar help-blank-line-regexp "\n\n+")

(with-current-buffer "*Help*"
  (let ((inhibit-read-only t))
    (save-excursion
      (goto-char (point-min))
      (while (re-search-forward help-blank-line-regexp nil t)
        (font-lock-append-text-property
         (match-beginning 0) (match-end 0)
         'font-lock-face `(:height ,help-blank-line-height))))))

Of course, you could use that loop instead to add a font-lock-multiline property to the newlines, and then use this:

(with-current-buffer "*Help*"
  (font-lock-add-keywords nil '(("\n\n+" 0 `(face (:height 0.5))))))

But that sounds like more code for no added benefit. The simplest solution is probably to change the function that inserts the docstring to insert a string with the right properties applied.

Clément.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: Paragraph styles in doc strings

[Stefan Monnier]

> I'm not sure font-lock will work nicely for this. Blank lines are
> a multi-line pattern.

Actually, no, "^\n" is not a multi-line pattern (yes, it's right there
on the border, but it's on the right side of the fence).  And "^\n+"
should work as well (as long as we the behavior is the same as with
"^\n", tho slightly optimized), even though it *is*
a multi-line pattern.

> (with-current-buffer "*Help*"
>   (let ((inhibit-read-only t))
>     (save-excursion
>       (goto-char (point-min))
>       (while (re-search-forward help-blank-line-regexp nil t)
>         (font-lock-append-text-property
>          (match-beginning 0) (match-end 0)
>          'font-lock-face `(:height ,help-blank-line-height))))))

Oh, I'm not so concerned about the *Help* buffers, it's the source code
that annoys me (that's where I work and where I don't want to waste
screen real-estate).


        Stefan

Re: Paragraph styles in doc strings

[Clément Pit--Claudel]

[-- Attachment #1.1.1: Type: text/plain, Size: 619 bytes --]

On 2016-06-01 21:18, Stefan Monnier wrote:
>> I'm not sure font-lock will work nicely for this. Blank lines are
>> a multi-line pattern.
> 
> Actually, no, "^\n" is not a multi-line pattern (yes, it's right there
> on the border, but it's on the right side of the fence).

Thanks, that's neat!

> Oh, I'm not so concerned about the *Help* buffers, it's the source code
> that annoys me (that's where I work and where I don't want to waste
> screen real-estate).

Ok, I understand the purpose more clearly now :)  What do you think of the attached package?  If it works, I can push it to ELPA.

Clément.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.1.2: compact-docstrings.el --]
[-- Type: text/x-emacs-lisp; name="compact-docstrings.el", Size: 3424 bytes --]

;;; compact-docstrings.el --- Shrink blank lines in docstrings and doc comments

;; Copyright (C) 2016  Clément Pit-Claudel

;; Author: Clément Pit-Claudel <clement.pitclaudel@live.com>
;; URL: https://github.com/cpitclaudel/compact-docstrings
;; Package-Version: 0.1
;; Keywords: convenience, faces, lisp, maint, c

;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <http://www.gnu.org/licenses/>.

;;; Commentary:

;; Shrink blank lines in docstrings and doc comments
;;
;; Enable locally with `compact-docstrings-mode':
;;   (add-hook 'some-mode-hook #'compact-docstrings-mode)
;;
;; Enable globally (in all programming modes) with
;;   (add-hook 'after-init-hook #'global-compact-docstrings--mode)

;;; Code:

(defgroup compact-docstrings nil
  "Shrink empty lines in docstrings and doc comments."
  :group 'faces)

(defface compact-docstrings-face
  '((t :height 0.5))
  "Face applied to blank lines in docstrings."
  :group 'compact-docstrings)

(defcustom compact-docstrings-only-doc-blocks t
  "When nil, also shrink blank lines in regular strings and comments."
  :group 'compact-docstrings
  :type 'boolean)

(defun compact-docstrings--matcher (bound)
  "Find blank line in docstring, looking in point .. BOUND."
  (let ((found nil))
    (while (and (not found) (re-search-forward "^\\s-*\n" bound t))
      (let ((syntax (syntax-ppss)))
        (when (and (or (nth 3 syntax)  ;; In string
                       (nth 4 syntax)) ;; In comment
                   (or (not compact-docstrings-only-doc-blocks)
                       (let ((face (get-text-property (point) 'face)))
                         (or (eq face 'font-lock-doc-face)
                             (and (listp face) (memq 'font-lock-doc-face face))))))
          (setq found t))))
    found))

(defconst compact-docstrings--keywords
  '((compact-docstrings--matcher 0 'compact-docstrings-face prepend)) 'append)

;;;###autoload
(define-minor-mode compact-docstrings-mode
  "Shrink empty lines in docstrings and doc comments."
  :lighter " compact"
  (if compact-docstrings-mode
      (font-lock-add-keywords nil compact-docstrings--keywords 'append)
    (font-lock-remove-keywords nil compact-docstrings--keywords))
  (if (fboundp #'font-lock-flush)
      (font-lock-flush)
    (with-no-warnings (font-lock-fontify-buffer))))

(defun compact-docstrings--mode-on ()
  "Turn on `compact-docstrings-mode', if appropriate."
  (when (derived-mode-p major-mode #'prog-mode)
    (compact-docstrings-mode)))

;;;###autoload
(defalias 'shrink-docstrings #'compact-docstrings--mode-on)

;;;###autoload
(define-globalized-minor-mode global-compact-docstrings-mode compact-docstrings-mode
  compact-docstrings--mode-on
  :init-value nil)

(provide 'compact-docstrings)
;;; compact-docstrings.el ends here

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: Paragraph styles in doc strings

[Stefan Monnier]

> Ok, I understand the purpose more clearly now :)  What do you think of the
> attached package?  If it works, I can push it to ELPA.

Nice, thank you.  Please push it.


        Stefan

Re: Paragraph styles in doc strings

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 262 bytes --]

On 2016-06-20 21:18, Stefan Monnier wrote:
>> Ok, I understand the purpose more clearly now :)  What do you think of the
>> attached package?  If it works, I can push it to ELPA.
> 
> Nice, thank you.  Please push it.

Ok :) Will do so this week-end.



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]