Function: byte-compile-docstring-style-warn

byte-compile-docstring-style-warn is a byte-compiled function defined in bytecomp.el.gz.

Signature

(byte-compile-docstring-style-warn FORM)

Documentation

Warn if there are stylistic problems with the docstring in FORM.

Warn if documentation string of FORM is too wide. It is too wide if it has any lines longer than the largest of fill-column and byte-compile-docstring-max-column.

Aliases

byte-compile-docstring-length-warn (obsolete since 29.1)

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/bytecomp.el.gz
(defun byte-compile-docstring-style-warn (form)
  "Warn if there are stylistic problems with the docstring in FORM.
Warn if documentation string of FORM is too wide.
It is too wide if it has any lines longer than the largest of
`fill-column' and `byte-compile-docstring-max-column'."
  (when (byte-compile-warning-enabled-p 'docstrings)
    (let ((col (max byte-compile-docstring-max-column fill-column))
          kind name docs)
      (pcase (car form)
        ((or 'autoload 'custom-declare-variable 'defalias
             'defconst 'define-abbrev-table
             'defvar 'defvaralias
             'custom-declare-face)
         (setq kind (nth 0 form))
         (setq name (nth 1 form))
         (setq docs (nth 3 form)))
        ('lambda
          (setq kind "")          ; can't be "function", unfortunately
          (setq docs (and (stringp (nth 2 form))
                          (nth 2 form)))))
      (when (and (consp name) (eq (car name) 'quote))
        (setq name (cadr name)))
      (setq name (if name (format " `%s' " name) ""))
      (when (and kind docs (stringp docs))
        (when (byte-compile--wide-docstring-p docs col)
          (byte-compile-warn-x
           name
           "%s%sdocstring wider than %s characters"
           kind name col))
        ;; There's a "naked" ' character before a symbol/list, so it
        ;; should probably be quoted with \=.
        (when (string-match-p "\\( [\"#]\\|[ \t]\\|^\\)'[a-z(]" docs)
          (byte-compile-warn-x
           name "%s%sdocstring has wrong usage of unescaped single quotes (use \\= or different quoting)"
           kind name))
        ;; There's a "Unicode quote" in the string -- it should probably
        ;; be an ASCII one instead.
        (when (byte-compile-warning-enabled-p 'docstrings-non-ascii-quotes)
          (when (string-match-p "\\( \"\\|[ \t]\\|^\\)[‘’]" docs)
            (byte-compile-warn-x
             name "%s%sdocstring has wrong usage of \"fancy\" single quotation marks"
             kind name))))))
  form)