Function: derived-mode-make-docstring

derived-mode-make-docstring is a byte-compiled function defined in derived.el.gz.

Signature

(derived-mode-make-docstring PARENT CHILD &optional DOCSTRING SYNTAX ABBREV)

Documentation

Construct a docstring for a new mode if none is provided.

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/derived.el.gz
;;; PRIVATE

(defun derived-mode-make-docstring (parent child &optional
					   docstring syntax abbrev)
  "Construct a docstring for a new mode if none is provided."

  (let ((map (derived-mode-map-name child))
	(hook (derived-mode-hook-name child)))

    (unless (stringp docstring)
      ;; Use a default docstring.
      (setq docstring
	    (if (null parent)
                (concat
                 "Major-mode.\n"
                 (internal--format-docstring-line
                  "Uses keymap `%s'%s%s." map
                  (if abbrev (format "%s abbrev table `%s'"
                                     (if syntax "," " and") abbrev) "")
                  (if syntax (format " and syntax-table `%s'" syntax) "")))
	      (format "Major mode derived from `%s' by `define-derived-mode'.
It inherits all of the parent's attributes, but has its own keymap%s:

%s

which more-or-less shadow%s %s's corresponding table%s."
		      parent
		      (cond ((and abbrev syntax)
			     ",\nabbrev table and syntax table")
			    (abbrev "\nand abbrev table")
			    (syntax "\nand syntax table")
			    (t ""))
                      (internal--format-docstring-line
                       "  `%s'%s"
                       map
                       (cond ((and abbrev syntax)
                              (format ", `%s' and `%s'" abbrev syntax))
                             ((or abbrev syntax)
                              (format " and `%s'" (or abbrev syntax)))
                             (t "")))
		      (if (or abbrev syntax) "" "s")
		      parent
		      (if (or abbrev syntax) "s" "")))))

    (unless (string-match (regexp-quote (symbol-name hook)) docstring)
      ;; Make sure the docstring mentions the mode's hook.
      (setq docstring
            (concat docstring "\n\n"
                    (internal--format-docstring-line
                     "%s%s%s"
                     (if (null parent)
                         "This mode "
                       (concat
                        "In addition to any hooks its parent mode "
                        (if (string-match (format "[`‘]%s['’]"
                                                  (regexp-quote
                                                   (symbol-name parent)))
                                          docstring)
                            nil
                          (format "`%s' " parent))
                        "might have run, this mode "))
                     (format "runs the hook `%s'" hook)
                     ", as the final or penultimate step during initialization."))))

    (unless (string-match "\\\\[{[]" docstring)
      ;; And don't forget to put the mode's keymap.
      (setq docstring (concat docstring "\n\n\\{" (symbol-name map) "}")))

    docstring))