From: Emanuel Berg <moasenwood@zoho.eu>
To: Eli Zaretskii <eliz@gnu.org>
Cc: 35164@debbugs.gnu.org
Subject: bug#35164: 25.1; `re-search-forward' docstring args
Date: Sat, 06 Apr 2019 09:09:22 +0200 [thread overview]
Message-ID: <86r2afbof1.fsf@zoho.eu> (raw)
In-Reply-To: <83ef6fbqsz.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 06 Apr 2019 09:17:48 +0300")
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
next prev parent reply other threads:[~2019-04-06 7:09 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-04-05 18:59 bug#35164: 25.1; `re-search-forward' docstring args Emanuel Berg
2019-04-06 6:17 ` Eli Zaretskii
2019-04-06 7:09 ` Emanuel Berg [this message]
2019-04-06 8:59 ` Eli Zaretskii
2019-04-06 14:30 ` Emanuel Berg
2019-04-06 14:33 ` Eli Zaretskii
2019-04-06 14:35 ` Emanuel Berg
2019-04-06 15:15 ` Alex Branham
2019-04-06 15:57 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=86r2afbof1.fsf@zoho.eu \
--to=moasenwood@zoho.eu \
--cc=35164@debbugs.gnu.org \
--cc=eliz@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.