From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Emanuel Berg Newsgroups: gmane.emacs.bugs Subject: bug#35164: 25.1; `re-search-forward' docstring args Date: Sat, 06 Apr 2019 09:09:22 +0200 Message-ID: <86r2afbof1.fsf@zoho.eu> References: <861s2gffd3.fsf@zoho.eu> <83ef6fbqsz.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="28463"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux) Cc: 35164@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Apr 06 09:19:15 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hCfbe-0007FY-Td for geb-bug-gnu-emacs@m.gmane.org; Sat, 06 Apr 2019 09:19:15 +0200 Original-Received: from localhost ([127.0.0.1]:51639 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hCfbd-0007qT-UD for geb-bug-gnu-emacs@m.gmane.org; Sat, 06 Apr 2019 03:19:13 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:36401) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hCfb1-0007L9-5i for bug-gnu-emacs@gnu.org; Sat, 06 Apr 2019 03:18:36 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hCfSk-0001tU-Qf for bug-gnu-emacs@gnu.org; Sat, 06 Apr 2019 03:10:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:32958) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hCfSk-0001tL-Hw for bug-gnu-emacs@gnu.org; Sat, 06 Apr 2019 03:10:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hCfSk-0003RK-AW for bug-gnu-emacs@gnu.org; Sat, 06 Apr 2019 03:10:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Emanuel Berg Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 06 Apr 2019 07:10:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 35164 X-GNU-PR-Package: emacs Original-Received: via spool by 35164-submit@debbugs.gnu.org id=B35164.155453457013154 (code B ref 35164); Sat, 06 Apr 2019 07:10:02 +0000 Original-Received: (at 35164) by debbugs.gnu.org; 6 Apr 2019 07:09:30 +0000 Original-Received: from localhost ([127.0.0.1]:46498 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hCfSE-0003Q6-0B for submit@debbugs.gnu.org; Sat, 06 Apr 2019 03:09:30 -0400 Original-Received: from sender-pp-o92.zoho.eu ([185.20.209.252]:25750) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hCfSC-0003Py-54 for 35164@debbugs.gnu.org; Sat, 06 Apr 2019 03:09:28 -0400 ARC-Seal: i=1; a=rsa-sha256; t=1554534563; cv=none; d=zohomail.eu; s=zohoarc; b=QjEVSUE73alqHtuh4CjxDjwNUj4BAH1TYEgSheeq8px/mmju+Fo1MsV4nljHYAiuHB6NCzhCiM40UdEf5aptjs9AA2QsItcnKLJS3KwmlHFOtEU29LBJeRygS4v7qVevAnRfPI2jm/KcHb1oIQCQG2GnWYYUngmzrl3PZA1EQmY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.eu; s=zohoarc; t=1554534563; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:To:ARC-Authentication-Results; bh=U2NLsSWnNb5UMt4YAG+uvQSNFnPdaNdLgdLt09YMV1A=; b=RI8Tow3IUO2hRKXOlZhHZVYI1j7GQhPQLH1AvyYddQYOwq13JdExZHGJrAIRlDAm5JzXb/qDnn1d/qLjpTEyMhPXRQbSjXJqZW0NgL9O/JwFQxtqPu6P9LV80fcy1vTvgEMVCmm4GJfhSczB5XyOiCi8Swgb3UYX1daGLYb1VTE= ARC-Authentication-Results: i=1; mx.zohomail.eu; dkim=pass header.i=zoho.eu; spf=pass smtp.mailfrom=moasenwood@zoho.eu; dmarc=pass header.from= header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1554534563; s=admin; d=zoho.eu; i=moasenwood@zoho.eu; h=From:To:Cc:Message-ID:Subject:References:Date:In-Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding; l=3455; bh=U2NLsSWnNb5UMt4YAG+uvQSNFnPdaNdLgdLt09YMV1A=; b=LlxX1y1tokTWbsaCtbQBGQek5gTsorhIykJYzxwO6l5L2xdrhER8D5p9dHCCEdQd Ja441zp2Y7ncIzF7zEpZILac+2Dr79eQYZgCL2jKKdT2+fggy6SeuxCXy9p8ruQ1A8Z yKPLqdM64G5YXGp6ibUfyeZGUFupjd1Ay8ufRV9E= Original-Received: from raspberrypi.zoho.eu (c-b895225c.021-67-7570702.bbcust.telenor.se [92.34.149.184]) by mx.zoho.eu with SMTPS id 1554534562811200.64361887557425; Sat, 6 Apr 2019 09:09:22 +0200 (CEST) Mail-Copies-To: never In-Reply-To: <83ef6fbqsz.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 06 Apr 2019 09:17:48 +0300") X-ZohoMailClient: External X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:157251 Archived-At: 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 =E2=80=98bound=E2=80=99 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 =E2=80=98case-fold-search=E2=80=99, which see. See also the functions =E2=80=98match-beginning=E2=80=99, =E2=80=98match-en= d=E2=80=99, =E2=80=98match-string=E2=80=99, and =E2=80=98replace-match=E2=80=99." (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 --=20 underground experts united http://user.it.uu.se/~embe8573