Make help-split-fundoc more flexible about what returns
* lisp/help.el (help-split-fundoc): New arg SECTION to return only the usage or doc parts of the docstring, or both even if there is no usage. * test/lisp/help-tests.el: New file.
This commit is contained in:
Juanma Barranquero
parent
4b5d04be44
commit
6f3ff47c52
2 changed files with 84 additions and 16 deletions
44
lisp/help.el
44
lisp/help.el
|
|
@ -1380,27 +1380,39 @@ The result, when formatted by `substitute-command-keys', should equal STRING."
|
|||
;; But for various reasons, they are more widely needed, so they were
|
||||
;; moved to this file, which is preloaded. https://debbugs.gnu.org/17001
|
||||
|
||||
(defun help-split-fundoc (docstring def)
|
||||
(defun help-split-fundoc (docstring def &optional section)
|
||||
"Split a function DOCSTRING into the actual doc and the usage info.
|
||||
Return (USAGE . DOC) or nil if there's no usage info, where USAGE info
|
||||
is a string describing the argument list of DEF, such as
|
||||
\"(apply FUNCTION &rest ARGUMENTS)\".
|
||||
DEF is the function whose usage we're looking for in DOCSTRING."
|
||||
Return (USAGE . DOC), where USAGE is a string describing the argument
|
||||
list of DEF, such as \"(apply FUNCTION &rest ARGUMENTS)\".
|
||||
DEF is the function whose usage we're looking for in DOCSTRING.
|
||||
With SECTION nil, return nil if there is no usage info; conversely,
|
||||
SECTION t means to return (USAGE . DOC) even if there's no usage info.
|
||||
When SECTION is \\='usage or \\='doc, return only that part."
|
||||
;; Functions can get the calling sequence at the end of the doc string.
|
||||
;; In cases where `function' has been fset to a subr we can't search for
|
||||
;; function's name in the doc string so we use `fn' as the anonymous
|
||||
;; function name instead.
|
||||
(when (and docstring (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" docstring))
|
||||
(let ((doc (unless (zerop (match-beginning 0))
|
||||
(substring docstring 0 (match-beginning 0))))
|
||||
(usage-tail (match-string 1 docstring)))
|
||||
(cons (format "(%s%s"
|
||||
;; Replace `fn' with the actual function name.
|
||||
(if (symbolp def)
|
||||
(help--docstring-quote (format "%S" def))
|
||||
'anonymous)
|
||||
usage-tail)
|
||||
doc))))
|
||||
(let* ((found (and docstring
|
||||
(string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" docstring)))
|
||||
(doc (if found
|
||||
(and (memq section '(t nil doc))
|
||||
(not (zerop (match-beginning 0)))
|
||||
(substring docstring 0 (match-beginning 0)))
|
||||
docstring))
|
||||
(usage (and found
|
||||
(memq section '(t nil usage))
|
||||
(let ((tail (match-string 1 docstring)))
|
||||
(format "(%s%s"
|
||||
;; Replace `fn' with the actual function name.
|
||||
(if (and (symbolp def) def)
|
||||
(help--docstring-quote (format "%S" def))
|
||||
'anonymous)
|
||||
tail)))))
|
||||
(pcase section
|
||||
(`nil (and usage (cons usage doc)))
|
||||
(`t (cons usage doc))
|
||||
(`usage usage)
|
||||
(`doc doc))))
|
||||
|
||||
(defun help-add-fundoc-usage (docstring arglist)
|
||||
"Add the usage info to DOCSTRING.
|
||||
|
|
|
|||
56
test/lisp/help-tests.el
Normal file
56
test/lisp/help-tests.el
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
;;; help-tests.el --- Tests for help.el -*- lexical-binding: t; -*-
|
||||
|
||||
;; Copyright (C) 2019 Free Software Foundation, Inc.
|
||||
|
||||
;; Author: Juanma Barranquero <lekktu@gmail.com>
|
||||
;; Keywords: help, internal
|
||||
|
||||
;; This file is part of GNU Emacs.
|
||||
|
||||
;; GNU Emacs is free software: you can redistribute it and/or modify
|
||||
;; it under the terms of the GNU General Public License as published by
|
||||
;; the Free Software Foundation, either version 3 of the License, or
|
||||
;; (at your option) any later version.
|
||||
|
||||
;; GNU Emacs is distributed in the hope that it will be useful,
|
||||
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
;; GNU General Public License for more details.
|
||||
|
||||
;; You should have received a copy of the GNU General Public License
|
||||
;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
;;; Code:
|
||||
|
||||
(require 'ert)
|
||||
|
||||
(ert-deftest help-split-fundoc-SECTION ()
|
||||
"Test new optional arg SECTION."
|
||||
(let* ((doc "Doc first line.\nDoc second line.")
|
||||
(usg "\n\n(fn ARG1 &optional ARG2)")
|
||||
(full (concat doc usg))
|
||||
(usage "(t ARG1 &optional ARG2)"))
|
||||
;; Docstring has both usage and doc
|
||||
(should (equal (help-split-fundoc full t nil) `(,usage . ,doc)))
|
||||
(should (equal (help-split-fundoc full t t) `(,usage . ,doc)))
|
||||
(should (equal (help-split-fundoc full t 'usage) usage))
|
||||
(should (equal (help-split-fundoc full t 'doc) doc))
|
||||
;; Docstring has no usage, only doc
|
||||
(should (equal (help-split-fundoc doc t nil) nil))
|
||||
(should (equal (help-split-fundoc doc t t) `(nil . ,doc)))
|
||||
(should (equal (help-split-fundoc doc t 'usage) nil))
|
||||
(should (equal (help-split-fundoc doc t 'doc) doc))
|
||||
;; Docstring is only usage, no doc
|
||||
(should (equal (help-split-fundoc usg t nil) `(,usage . nil)))
|
||||
(should (equal (help-split-fundoc usg t t) `(,usage . nil)))
|
||||
(should (equal (help-split-fundoc usg t 'usage) usage))
|
||||
(should (equal (help-split-fundoc usg t 'doc) nil))
|
||||
;; Docstring is null
|
||||
(should (equal (help-split-fundoc nil t nil) nil))
|
||||
(should (equal (help-split-fundoc nil t t) '(nil)))
|
||||
(should (equal (help-split-fundoc nil t 'usage) nil))
|
||||
(should (equal (help-split-fundoc nil t 'doc) nil))))
|
||||
|
||||
(provide 'help-tests)
|
||||
|
||||
;;; help-tests.el ends here
|
||||
Loading…
Add table
Reference in a new issue