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 DOCS KIND NAME)

Documentation

Warn if there are stylistic problems in the docstring DOCS.

Warn if documentation string 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.

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/bytecomp.el.gz
(defun byte-compile--docstring-style-warn (docs kind name)
  "Warn if there are stylistic problems in the docstring DOCS.
Warn if documentation string 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* ((name (if (eq (car-safe name) 'quote) (cadr name) name))
           (prefix (lambda ()
                     (format "%s%s"
                             kind
                             (if name (format-message " `%S' " name) "")))))
      (let ((col (max byte-compile-docstring-max-column fill-column)))
        (when (and (byte-compile-warning-enabled-p 'docstrings-wide)
                   (byte-compile--wide-docstring-p docs col))
          (byte-compile-warn-x
           name
           "%sdocstring wider than %s characters" (funcall prefix) col)))

      (when (byte-compile-warning-enabled-p 'docstrings-control-chars)
        (let ((start 0)
              (len (length docs)))
          (while (and (< start len)
                      (string-match (rx (intersection (in (0 . 31) 127)
                                                      (not (in "\n\t"))))
                                    docs start))
            (let* ((ofs (match-beginning 0))
                   (c (aref docs ofs)))
              ;; FIXME: it should be possible to use the exact source position
              ;; of the control char in most cases, and it would be helpful
              (byte-compile-warn-x
               name
               "%sdocstring contains control char #x%02x (position %d)"
               (funcall prefix) c ofs)
              (setq start (1+ ofs))))))

      ;; There's a "naked" ' character before a symbol/list, so it
      ;; should probably be quoted with \=.
      (when (string-match-p (rx (| (in " \t") bol)
                                (? (in "\"#"))
                                "'"
                                (in "A-Za-z" "("))
                            docs)
        (byte-compile-warn-x
         name
         (concat "%sdocstring has wrong usage of unescaped single quotes"
                 " (use \\=%c or different quoting such as %c...%c)")
         (funcall prefix) ?' ?` ?'))
      ;; 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 (rx (| " \"" (in " \t") bol)
                                  (in "‘’"))
                              docs)
          (byte-compile-warn-x
           name
           "%sdocstring uses curved single quotes; use %s instead of ‘...’"
           (funcall prefix) "`...'"))))))