From 6f3ff47c521a41f3eab3efd1f6126f06f4171478 Mon Sep 17 00:00:00 2001 From: Juanma Barranquero Date: Sat, 23 Nov 2019 23:29:53 +0100 Subject: [PATCH] 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. --- lisp/help.el | 44 ++++++++++++++++++++------------ test/lisp/help-tests.el | 56 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 16 deletions(-) create mode 100644 test/lisp/help-tests.el diff --git a/lisp/help.el b/lisp/help.el index 22f35df1de1..06264ae2f32 100644 --- a/lisp/help.el +++ b/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. diff --git a/test/lisp/help-tests.el b/test/lisp/help-tests.el new file mode 100644 index 00000000000..28dd8830e44 --- /dev/null +++ b/test/lisp/help-tests.el @@ -0,0 +1,56 @@ +;;; help-tests.el --- Tests for help.el -*- lexical-binding: t; -*- + +;; Copyright (C) 2019 Free Software Foundation, Inc. + +;; Author: Juanma Barranquero +;; 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 . + +;;; 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 -- 2.39.2