bug#35164: 25.1; `re-search-forward' docstring args

bug#35164: 25.1; `re-search-forward' docstring args

[Emanuel Berg]

The `re-search-forward' docstring does not
mention its arguments according to the norm.
And it makes sense, often the first thing I do
when I bring up the help buffer for a function
is to search for a particular argument to see
what it does.



In GNU Emacs 25.1.1 (arm-unknown-linux-gnueabihf, GTK+ Version 3.22.11)
 of 2017-09-16, modified by Debian built on bm-wb-02
System Description:	Raspbian GNU/Linux 9.8 (stretch)

Configured using:
 'configure --build arm-linux-gnueabihf
 --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/emacs25:/etc/emacs:/usr/local/share/emacs/25.1/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/25.1/site-lisp:/usr/share/emacs/site-lisp
 --with-sound=alsa --build arm-linux-gnueabihf
 --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/emacs25:/etc/emacs:/usr/local/share/emacs/25.1/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/25.1/site-lisp:/usr/share/emacs/site-lisp
 --with-sound=alsa --with-x=yes
 --with-x-toolkit=gtk3
 --with-toolkit-scroll-bars 'CFLAGS=-g -O2
 -fdebug-prefix-map=/build/emacs25-pkwV6G/emacs25-25.1+1=.
 -fstack-protector-strong -Wformat
 -Werror=format-security -Wall'
 'CPPFLAGS=-Wdate-time -D_FORTIFY_SOURCE=2'
 LDFLAGS=-Wl,-z,relro'

Configured features:
XPM JPEG TIFF GIF PNG RSVG IMAGEMAGICK SOUND
GPM DBUS GCONF GSETTINGS NOTIFY ACL LIBSELINUX
GNUTLS LIBXML2 FREETYPE M17N_FLT LIBOTF XFT
ZLIB TOOLKIT_SCROLL_BARS GTK3 X11

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

Major mode: Help

Minor modes in effect:
  show-paren-mode: t
  shell-dirtrack-mode: t
  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-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
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-compression-mode: t
  buffer-read-only: t
  transient-mark-mode: t

Recent messages:
next-line: End of buffer [3 times]
previous-line: Beginning of buffer [6 times]
 This is the one occurrence. [6 times]
Type "q" to restore previous buffer, M-x scroll-up to scroll help.
 hit: 125
 This is the one occurrence. [2 times]
Mark set
Saving file /home/incal/ooa/doodle.el...
Wrote /home/incal/ooa/doodle.el
Quit

Load-path shadows:
/usr/share/emacs/25.1/site-lisp/debian-startup hides /usr/share/emacs/site-lisp/debian-startup
/usr/share/emacs25/site-lisp/flim/md4 hides /usr/share/emacs/25.1/lisp/md4
/usr/share/emacs25/site-lisp/flim/hex-util hides /usr/share/emacs/25.1/lisp/hex-util
~/.emacs.d/lisp/abbrev hides /usr/share/emacs/25.1/lisp/abbrev
~/.emacs.d/emacs-init/gnus/server hides /usr/share/emacs/25.1/lisp/server
/usr/share/emacs25/site-lisp/flim/sasl-ntlm hides /usr/share/emacs/25.1/lisp/net/sasl-ntlm
/usr/share/emacs25/site-lisp/flim/sasl-cram hides /usr/share/emacs/25.1/lisp/net/sasl-cram
/usr/share/emacs25/site-lisp/flim/ntlm hides /usr/share/emacs/25.1/lisp/net/ntlm
/usr/share/emacs25/site-lisp/flim/sasl hides /usr/share/emacs/25.1/lisp/net/sasl
/usr/share/emacs25/site-lisp/flim/hmac-def hides /usr/share/emacs/25.1/lisp/net/hmac-def
/usr/share/emacs25/site-lisp/flim/hmac-md5 hides /usr/share/emacs/25.1/lisp/net/hmac-md5
/usr/share/emacs25/site-lisp/flim/sasl-digest hides /usr/share/emacs/25.1/lisp/net/sasl-digest
/home/incal/.emacs.d/elpa/seq-2.20/seq hides /usr/share/emacs/25.1/lisp/emacs-lisp/seq
/home/incal/.emacs.d/elpa/let-alist-1.0.5/let-alist hides /usr/share/emacs/25.1/lisp/emacs-lisp/let-alist

Features:
(shadow emacsbug conf-mode mm-archive sh-script
smie executable mailalias w3m-cookie canlock
url-http url-gw url-cache url-auth mail-extr qp
gnus-async gnus-bcklg gnus-ml make-mode
eieio-opt speedbar sb-image ezimage dframe
find-func whitespace cus-edit cus-start
cus-load tabify nnir cursor-sensor pop3 nndraft
nnmh nnml network-stream nsm starttls
gnus-agent nnvirtual nntp gnus-cache w3m-filter
ffap paren xsel w3m-form
google-translate-core-ui ido
google-translate-core google-translate-tk url
url-proxy url-privacy url-expand url-methods
url-history url-cookie url-domsuf url-util
url-parse url-vars json map lpr tramp-sh term
disp-table ehelp my-faces t-mouse man tex-mode
iterate-files seq-24 isbn my-bibtex bibtex
slime-presentations slime-repl slime-parse
bridge nroff-mode sgml-mode cobol-mode ada-mode
which-func imenu align find-file checkdoc
cc-mode cc-fonts cc-guess cc-menus cc-cmds
cc-styles cc-align cc-engine cc-vars cc-defs
guile summary message-my moggle mail-to-many
mail smtpmail sendmail font-lock-add
global-keys yank-my wrap-search w3m-unisearch
w3m-search spell-new ispell sort-my sort slime
etags xref project arc-mode archive-mode
noutline outline easy-mmode hyperspec shell-cli
revert-buffer-my lisp-new ielm kill keys
help-new debug apropos dired-x compile-my
mode-line compile article gnus-cite dl
bookmarks w3m-bookmark file-write-to erc-my
fill-new quit gnus-my group group-summary
gnus-srvr gnus-score score-mode gnus-msg
gnus-art mm-uu mml2015 mm-view mml-smime smime
dig mailcap gnus-sum gnus-group gnus-undo
gnus-start gnus-cloud nnimap nnmail mail-source
tls gnutls utf7 netrc nnoo parse-time gnus-spec
gnus-int gnus-range gnus-win message rfc822 mml
mml-sec epg mm-decode mm-bodies mm-encode
mail-parse rfc2231 rfc2047 rfc2045 ietf-drums
mailabbrev gmm-utils mailheader gnus gnus-ems
nnheader mail-utils edit tabs dired-my w3m-my
w3m-tabs w3m-session w3m browse-url doc-view
jka-compr image-mode timezone w3m-hist w3m-fb
bookmark-w3m w3m-ems w3m-ccl ccl w3m-favicon
w3m-image w3m-proc w3m-util time-my linux-shell
files-my tramp tramp-compat tramp-loaddefs
trampver ucs-normalize shell advice
sudo-user-path find-command window-new count
get-search-string caps-back buffer-menu
switch-to-buffer super scroll dired close buc
switch-to-buffer-regexp subr-x align-new
erc-list erc-menu erc-join erc-ring
erc-networks erc-pcomplete pcomplete comint
ansi-color ring erc-track erc-match erc-button
wid-edit erc-fill erc-stamp erc-netsplit
erc-goodies erc erc-backend erc-compat
format-spec auth-source cl-seq eieio eieio-core
cl-macs gnus-util time-date mm-util help-fns
mail-prsvr password-cache thingatpt pp
my-string search-regexp-in-files finder-inf
info slime-autoloads package epg-config seq
byte-opt gv bytecomp byte-compile cl-extra
help-mode easymenu cconv cl-loaddefs pcase
cl-lib w3m-load mule-util tooltip eldoc
electric uniquify ediff-hook vc-hooks
lisp-float-type mwheel x-win term/common-win
x-dnd tool-bar dnd fontset image regexp-opt
fringe tabulated-list newcomment elisp-mode
lisp-mode prog-mode register page menu-bar
rfn-eshadow timer select scroll-bar mouse
jit-lock font-lock syntax facemenu font-core
frame cl-generic cham georgian utf-8-lang
misc-lang vietnamese tibetan thai tai-viet lao
korean japanese eucjp-ms cp51932 hebrew greek
romanian slovak czech european ethiopic indian
cyrillic chinese charscript case-table epa-hook
jka-cmpr-hook help simple abbrev minibuffer
cl-preloaded 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 dbusbind inotify dynamic-setting
system-font-setting font-render-setting
move-toolbar gtk x-toolkit x multi-tty
make-network-process emacs)

Memory information:
((conses 8 568743 119463)
 (symbols 24 49702 123)
 (miscs 20 430 2699)
 (strings 16 124676 18964)
 (string-bytes 1 3755177)
 (vectors 8 73911)
 (vector-slots 4 1902907 47046)
 (floats 8 609 647)
 (intervals 28 11167 1807)
 (buffers 520 100))

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35164: 25.1; `re-search-forward' docstring args

[Eli Zaretskii]

> From: Emanuel Berg <moasenwood@zoho.eu>
> Date: Fri, 05 Apr 2019 20:59:04 +0200
> 
> The `re-search-forward' docstring does not
> mention its arguments according to the norm.
> And it makes sense, often the first thing I do
> when I bring up the help buffer for a function
> is to search for a particular argument to see
> what it does.

All the arguments are mentioned in the doc string, so I don't think I
understand this report.  What "norm" are you alluding to, and how
exactly does the doc string violate it?

bug#35164: 25.1; `re-search-forward' docstring args

[Emanuel Berg]

Eli Zaretskii wrote:

> All the arguments are mentioned in the doc
> string, so I don't think I understand this
> report. What "norm" are you alluding to, and
> how exactly does the doc string violate it?

;;; docstring-experiment.el --- illustrate docstring deficiency

;;; Commentary:
;;;
;;; This file:
;;; http://user.it.uu.se/~embe8573/emacs-init/docstring-experiment.el
;;;
;;; Updated:  2019-04-06  09:05
;;;
;;; The purpose of this package is to
;;; illustrate the deficiency of certain
;;; docstrings with respect to the arguments of
;;; the functions.
;;;
;;; The first example docstring is from
;;; `re-search-forward' on GNU Emacs 25.1.1
;;; (arm-unknown-linux-gnueabihf, GTK+ Version
;;; 3.22.11) of 2017-09-16, modified by Debian.
;;;
;;; To illustrate even further, I have
;;; purposefully written an even worse
;;; docstring to a function that only
;;; exists here.
;;;
;;; To test, evaluate:
;;;
;;;     (checkdoc-current-buffer t)
;;;
;;; Here is some additional settings and
;;; helpers:
;;;
;;;     (require 'checkdoc)
;;;     (setq checkdoc-permit-comma-termination-flag t)
;;;
;;;     (defun check-package-style ()
;;;       (interactive)
;;;       (checkdoc-current-buffer t) ; TAKE-NOTES
;;;       (message "Style check done.") )
;;;     (defalias 'pack-style #'check-package-style)
;;;
;;; If you for some reason do not get
;;; `checkdoc' to work, the output is:
;;;
;;; *** docstring-experiment.el: checkdoc-current-buffer V 0.6.1
;;; docstring-experiment.el:37:
;;;   Argument ‘bound’ should appear (as BOUND) in the doc string
;;; docstring-experiment.el:60:
;;;   Arguments occur in the doc string out of order

;;; Code:

(defun illo-re-search-forward (regexp &optional bound noerror count)
  "Search forward from point for regular expression REGEXP.
Set point to the end of the occurrence found, and return point.
An optional second argument bounds the search; it is a buffer position.
  The match found must not end after that position.  A value of nil
  means search to the end of the accessible portion of the buffer.
Optional third argument, if t, means if fail just return nil (no error).
  If not nil and not t, move to limit of search and return nil.
Optional fourth argument COUNT, if a positive number, means to search
  for COUNT successive occurrences.  If COUNT is negative, search
  backward, instead of forward, for -COUNT occurrences.  A value of
  nil means the same as 1.
With COUNT positive, the match found is the COUNTth one (or first,
  if COUNT is 1 or nil) in the buffer located entirely after the
  origin of the search; correspondingly with COUNT negative.

Search case-sensitivity is determined by the value of the variable
‘case-fold-search’, which see.

See also the functions ‘match-beginning’, ‘match-end’, ‘match-string’,
and ‘replace-match’."
  (message "This function's purpose was not to be executed.") )

(defun illo-even-worse (out of order)
  "OUT is a nice place after too much computer work.
By a bridge the sound of the water can be very relaxing.
It gets your thoughts back to ORDER.
OF all the things I can think of now that would be the nicest."
  (message "Evaluate (checkdoc-current-buffer t) instead!") )

(provide 'docstring-experiment)
;;; docstring-experiment.el ends here

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35164: 25.1; `re-search-forward' docstring args

[Eli Zaretskii]

> From: Emanuel Berg <moasenwood@zoho.eu>
> Cc: 35164@debbugs.gnu.org
> Date: Sat, 06 Apr 2019 09:09:22 +0200
> 
> Eli Zaretskii wrote:
> 
> > All the arguments are mentioned in the doc
> > string, so I don't think I understand this
> > report. What "norm" are you alluding to, and
> > how exactly does the doc string violate it?
> 
> ;;; docstring-experiment.el --- illustrate docstring deficiency

I don't think I understand how this answers my question.  Please humor
me and provide a direct answer.

TIA

bug#35164: 25.1; `re-search-forward' docstring args

[Emanuel Berg]

Eli Zaretskii wrote:

> I don't think I understand how this answers
> my question. Please humor me and provide
> a direct answer.

I'm dropping this issue 100%. I thought it
would be a quick fix, but if you want
docstrings that do not conform with your own
rules do it.

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35164: 25.1; `re-search-forward' docstring args

[Eli Zaretskii]

> From: Emanuel Berg <moasenwood@zoho.eu>
> Cc: 35164@debbugs.gnu.org
> Date: Sat, 06 Apr 2019 16:30:54 +0200
> 
> Eli Zaretskii wrote:
> 
> > I don't think I understand how this answers
> > my question. Please humor me and provide
> > a direct answer.
> 
> I'm dropping this issue 100%. I thought it
> would be a quick fix, but if you want
> docstrings that do not conform with your own
> rules do it.

Which rules, please?  I really don't think I understand that, and I
don't think I asked something that should trigger such a reaction.  I
mean, if you submit a bug report, and I ask for clarifying it, why
would you refuse?

bug#35164: 25.1; `re-search-forward' docstring args

[Emanuel Berg]

Eli Zaretskii wrote:

> Which rules, please? I really don't think
> I understand that, and I don't think I asked
> something that should trigger such
> a reaction. I mean, if you submit a bug
> report, and I ask for clarifying it, why
> would you refuse?

I have dropped this issue.

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35164: 25.1; `re-search-forward' docstring args

[Alex Branham]

On Sat 06 Apr 2019 at 17:33, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Emanuel Berg <moasenwood@zoho.eu>
>> Cc: 35164@debbugs.gnu.org
>> Date: Sat, 06 Apr 2019 16:30:54 +0200
>> 
>> Eli Zaretskii wrote:
>> 
>> > I don't think I understand how this answers
>> > my question. Please humor me and provide
>> > a direct answer.
>> 
>> I'm dropping this issue 100%. I thought it
>> would be a quick fix, but if you want
>> docstrings that do not conform with your own
>> rules do it.
>
> Which rules, please?  I really don't think I understand that, and I
> don't think I asked something that should trigger such a reaction.  I
> mean, if you submit a bug report, and I ask for clarifying it, why
> would you refuse?

I think this is a duplicate of bug#25193, which was fixed in the
emacs-25 branch but wasn't in Emacs 25.1; it first appeared in Emacs
25.2. See commit 0c55cf43e61537364ee7ea3d6ba77bb6ac3ef8a3.

Alex

bug#35164: 25.1; `re-search-forward' docstring args

[Eli Zaretskii]

> From: Alex Branham <branham@utexas.edu>
> Cc: Emanuel Berg <moasenwood@zoho.eu>,  35164@debbugs.gnu.org
> Date: Sat, 06 Apr 2019 10:15:09 -0500
> 
> > Which rules, please?  I really don't think I understand that, and I
> > don't think I asked something that should trigger such a reaction.  I
> > mean, if you submit a bug report, and I ask for clarifying it, why
> > would you refuse?
> 
> I think this is a duplicate of bug#25193, which was fixed in the
> emacs-25 branch but wasn't in Emacs 25.1; it first appeared in Emacs
> 25.2. See commit 0c55cf43e61537364ee7ea3d6ba77bb6ac3ef8a3.

Ah, okay, thanks.  This explains why I didn't understand the original
report: I was looking at the doc string in Emacs 26.

So I think we can close this bug.