;; 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.
--- /dev/null
+;;; 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