bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

Eli Zaretskii wrote:

>> The words START and END do not appear, in
>> that order, in the docstring. Actually, they
>> don't appear at all. That means they are
>> not searchable.
>
> This is a command, first and foremost.
> The primary goal of its doc string is to tell
> users (not Lisp programmers) how to use the
> command and what it does. In interactive
> usage, START and END come from the region and
> are not under user control explicitly.
>
> So I don't think there's anything wrong with
> this doc string.

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