bug#19926: 24.4; `ispell-comments-and-strings' (somewhat) unclear docstring

[Emanuel Berg]

The interface/docstring of
`ispell-comments-and-strings' is a bit unclear so I
had to examine the source to understand it. It says:

    (ispell-comments-and-strings ONLY-CURRENT)

    Check comments and strings in the current buffer
    for spelling errors.

It is not 100% clear what ONLY-CURRENT refers to,
especially since the docstring mentions the "current
buffer" which is an unrelated currency.

I think it should say something like: "If
ONLY-CURRENT, only spellcheck the string or comment
under point, otherwise spellcheck all strings and
comments in the current buffer."



In GNU Emacs 24.4.1 (x86_64-pc-linux-gnu)
 of 2014-10-25 on trouble, modified by Debian
System Description:     Debian GNU/Linux testing (jessie)

Configured using:
 `configure --build x86_64-linux-gnu --prefix=/usr
 --sharedstatedir=/var/lib --libexecdir=/usr/lib
 --localstatedir=/var/lib --infodir=/usr/share/info
 --mandir=/usr/share/man --with-pop=yes
 
--enable-locallisppath=/etc/emacs24:/etc/emacs:/usr/local/share/emacs/24.4/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/24.4/site-lisp:/usr/share/emacs/site-lisp
 --build x86_64-linux-gnu --prefix=/usr
 --sharedstatedir=/var/lib --libexecdir=/usr/lib
 --localstatedir=/var/lib --infodir=/usr/share/info
 --mandir=/usr/share/man --with-pop=yes
 
--enable-locallisppath=/etc/emacs24:/etc/emacs:/usr/local/share/emacs/24.4/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/24.4/site-lisp:/usr/share/emacs/site-lisp
 --with-x=no --without-gconf --without-gsettings
 'CFLAGS=-g -O2 -fstack-protector-strong -Wformat
 -Werror=format-security -Wall'
 CPPFLAGS=-D_FORTIFY_SOURCE=2 LDFLAGS=-Wl,-z,relro'

Important settings:
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Help

Minor modes in effect:
  erc-list-mode: t
  erc-menu-mode: t
  erc-autojoin-mode: t
  erc-ring-mode: t
  erc-networks-mode: t
  erc-pcomplete-mode: t
  erc-track-mode: t
  erc-match-mode: t
  erc-button-mode: t
  erc-fill-mode: t
  erc-stamp-mode: t
  erc-netsplit-mode: t
  erc-irccontrols-mode: t
  erc-noncommands-mode: t
  erc-move-to-prompt-mode: t
  erc-readonly-mode: t
  erc-scrolltobottom-mode: t
  shell-dirtrack-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-compression-mode: t
  buffer-read-only: t
  visual-line-mode: t
  transient-mark-mode: t

Recent input:
C-p C-p C-p C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-n C-n C-n C-x C-e C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-p C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-n ဃ ESC o ESC o C-j e e C-n C-n C-n 
C-n C-n C-n C-n C-n C-n C-f C-f C-f C-f C-f C-f C-f 
C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f 
C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f 
C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f 
C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f C-f 
C-f C-f C-f C-f C-f C-p C-p C-p C-p C-o e C-g ESC : 
( i s p e l l - b o DEL DEL c o m m e n t s - a n d 
- s t r i n g s SPC t ) RET SPC C-p C-e C-o e SPC C-g 
C-l l k k k k k k k k k k k k k k k k k k k k k k k 
k k i i i i i i C-u 1 0 RET k k k k k k k k k RET ESC 
o ESC p C-o k C-p C-p C-p C-p C-p C-p C-p C-p C-p C-f 
C-h f RET ESC o ESC p ဃ ESC x r e p o r t C-g C-n C-n 
C-n C-n C-n C-n C-@ C-n C-n C-e ESC w C-p C-a C-p ESC 
x i DEL r e p o r t - b u g RET

Recent messages:
Spell-checking region using ispell with american-insane dictionary...done
Spell-checking region using ispell with american-insane dictionary...done
Spell-checking region using ispell with american-insane dictionary...
Spell-checking suspended; use C-u M-$ to resume
pop3 retrieved 0KB (0%)
pop3 retrieved 4KB (55%)
pop3 retrieved 6KB (95%)
pop3 retrieved 7KB (100%)
Mark set
Type "q" to delete help window.

Load-path shadows:
/usr/share/emacs/24.4/site-lisp/debian-startup hides 
/usr/share/emacs/site-lisp/debian-startup
/usr/share/emacs24/site-lisp/flim/hex-util hides 
/usr/share/emacs/24.4/lisp/hex-util
/usr/share/emacs24/site-lisp/flim/md4 hides /usr/share/emacs/24.4/lisp/md4
/usr/share/emacs24/site-lisp/dictionaries-common/flyspell hides 
/usr/share/emacs/24.4/lisp/textmodes/flyspell
/usr/share/emacs24/site-lisp/dictionaries-common/ispell hides 
/usr/share/emacs/24.4/lisp/textmodes/ispell
/usr/share/emacs/site-lisp/rst hides /usr/share/emacs/24.4/lisp/textmodes/rst
/usr/share/emacs24/site-lisp/flim/sasl-cram hides 
/usr/share/emacs/24.4/lisp/net/sasl-cram
/usr/share/emacs24/site-lisp/flim/sasl-digest hides 
/usr/share/emacs/24.4/lisp/net/sasl-digest
/usr/share/emacs24/site-lisp/flim/ntlm hides /usr/share/emacs/24.4/lisp/net/ntlm
/usr/share/emacs24/site-lisp/flim/sasl-ntlm hides 
/usr/share/emacs/24.4/lisp/net/sasl-ntlm
/usr/share/emacs24/site-lisp/flim/hmac-md5 hides 
/usr/share/emacs/24.4/lisp/net/hmac-md5
/usr/share/emacs24/site-lisp/flim/sasl hides /usr/share/emacs/24.4/lisp/net/sasl
/usr/share/emacs24/site-lisp/flim/hmac-def hides 
/usr/share/emacs/24.4/lisp/net/hmac-def
/usr/share/emacs24/site-lisp/latex-cjk-thai/thai-word hides 
/usr/share/emacs/24.4/lisp/language/thai-word
/usr/share/emacs/24.4/lisp/faces hides ~/.emacs.d/emacs-init/faces
/usr/share/emacs/24.4/lisp/textmodes/fill hides ~/.emacs.d/emacs-init/fill
/usr/share/emacs/24.4/lisp/window hides ~/.emacs.d/emacs-init/window
/usr/share/emacs/24.4/lisp/obsolete/spell hides ~/.emacs.d/emacs-init/spell
/usr/share/emacs/24.4/lisp/help hides ~/.emacs.d/emacs-init/help
/usr/share/emacs/24.4/lisp/abbrev hides ~/.emacs.d/emacs-init/abbrev
/usr/share/emacs/24.4/lisp/misc hides ~/.emacs.d/emacs-init/misc
/usr/share/emacs/24.4/lisp/align hides ~/.emacs.d/emacs-init/align
/usr/share/emacs/24.4/lisp/server hides ~/.emacs.d/emacs-init/gnus/server

Features:
(shadow emacsbug canlock tramp-cache net-utils trace
eieio-opt speedbar sb-image ezimage dframe find-func
cus-edit cus-start cus-load flyspell latexenc nnir
tabify flow-fill gnus-cite qp mm-archive mail-extr
gnus-async gnus-bcklg gnus-kill gnus-ml disp-table
pop3 nndraft nnmh nnml nnfolder parse-time netrc
gnutls network-stream starttls tls gnus-agent
gnus-score score-mode nnvirtual nntp gnus-cache
w3m-cookie mule-util w3m-filter ffap url-parse
url-vars xsel wrap-search w3m-session dl w3m-tabs
w3m-bookmark w3m-form w3m browse-url doc-view
jka-compr image-mode timezone w3m-hist w3m-fb
bookmark-w3m w3m-ems w3m-ccl ccl w3m-favicon image
w3m-image w3m-proc w3m-util time-my tabs ispell sort
revert-buffer-my tramp-sh bibtex t-mouse man
linux-shell tex-mode iterate-files cl ielm checkdoc
compile-my mode-line compile cc-mode cc-fonts cc-guess
cc-menus cc-cmds cc-styles cc-align cc-engine cc-vars
cc-defs debug info tool-bar apropos help-mode summary
message-my moggle smtpmail sendmail lamer group
gnus-my gnus-srvr article gnus-msg gnus-art mm-uu
mml2015 mm-view mml-smime smime dig mailcap
file-write-to erc-list erc-menu erc-join erc-ring
erc-networks erc-pcomplete erc-track erc-match
erc-button erc-fill erc-stamp erc-netsplit erc-goodies
erc erc-backend erc-compat thingatpt pp package
epg-config edit dired-my files-my dired buc cl-macs gv
global-keys tramp tramp-compat auth-source eieio
byte-opt bytecomp byte-compile cconv eieio-core
password-cache tramp-loaddefs trampver shell pcomplete
comint regexp-opt ansi-color ring advice gnus-sum nnoo
gnus-group gnus-undo nnmail mail-source gnus-start
gnus-spec gnus-int gnus-range message format-spec
rfc822 mml easymenu mml-sec mm-decode mm-bodies
mm-encode mail-parse rfc2231 rfc2047 rfc2045
ietf-drums mailabbrev gmm-utils mailheader gnus-win
gnus gnus-ems nnheader gnus-util time-date mail-utils
mm-util help-fns mail-prsvr wid-edit cl-loaddefs
cl-lib paren debian-el debian-el-loaddefs w3m-load
tooltip electric uniquify ediff-hook vc-hooks
lisp-float-type tabulated-list newcomment lisp-mode
prog-mode register page menu-bar rfn-eshadow timer
select mouse jit-lock font-lock syntax facemenu
font-core frame cham georgian utf-8-lang misc-lang
vietnamese tibetan thai tai-viet lao korean japanese
hebrew greek romanian slovak czech european ethiopic
indian cyrillic chinese case-table epa-hook
jka-cmpr-hook help simple abbrev minibuffer nadvice
loaddefs button faces cus-face macroexp files
text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget hashtable-print-readable
backquote make-network-process dbusbind gfilenotify
multi-tty emacs)

Memory information:
((conses 16 374428 50306)
 (symbols 48 43402 52)
 (miscs 40 564 1661)
 (strings 32 97763 7544)
 (string-bytes 1 2993084)
 (vectors 16 38690)
 (vector-slots 8 710882 19975)
 (floats 8 360 374)
 (intervals 56 5942 239)
 (buffers 960 72)
 (heap 1024 39904 1249))

-- 
underground experts united