GNU bug report logs -
#35163
25.1; `narrow-to-region' docstring no mention of args
Previous Next
Reported by: Emanuel Berg <moasenwood <at> zoho.eu>
Date: Fri, 5 Apr 2019 18:54:02 UTC
Severity: wishlist
Found in version 25.1
Done: Eli Zaretskii <eliz <at> gnu.org>
Bug is archived. No further changes may be made.
Full log
Message #17 received at 35163 <at> debbugs.gnu.org (full text, mbox):
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
This bug report was last modified 6 years and 101 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.