GNU bug report logs - #18478
24.4.50; doc string of `clone-indirect-buffer'

Previous Next

Full log

Message #23 received at 18478 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 18478 <at> debbugs.gnu.org, Tom Willemse <tom <at> ryuslash.org>
Subject: RE: bug#18478: [Patch] Mention the return value of
 `clone-indirect-buffer'
Date: Wed, 17 Sep 2014 21:05:24 -0700 (PDT)

> > FWIW, I don't put a lot of stock in checkdoc, personally. ;-)
> 
> Its recommendations shouldn't be heeded blindly, indeed, but the
> 80-columns limit is something that should really be obeyed
> whenever possible.

Agreed wrt respecting doc-string line-length conventions.

But 80 chars is the absolute limit.  Doc strings should really be 
quite a bit shorter than that.  `emacs-lisp-docstring-fill-column'
defaults to 65, for example.

The actual convention is this (from (elisp) `Documentation Tips'):

 Format the documentation string so that it fits in an Emacs window
 on an 80-column screen.  It is a good idea for most lines to be no
 wider than 60 characters.  The first line should not be wider than
            ^^^^^^^^^^^^^
 67 characters or it will look bad in the output of `apropos'.

 You can fill the text if that looks good.  Emacs Lisp mode fills
 documentation strings to the width specified by
 `emacs-lisp-docstring-fill-column'.  However, you can sometimes
 make a documentation string much more readable by adjusting its
 line breaks with care.  Use blank lines between sections if the
 documentation string is long.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.