master 6f3ff47: Make help-split-fundoc more flexible about what returns

[Juanma Barranquero]

branch: master
commit 6f3ff47c521a41f3eab3efd1f6126f06f4171478
Author: Juanma Barranquero <address@hidden>
Commit: Juanma Barranquero <address@hidden>

    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(-)

diff --git a/lisp/help.el b/lisp/help.el
index 22f35df..06264ae 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 0000000..28dd883
--- /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 <address@hidden>
+;; 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