Re: master 49192e9: Strip "(fn...)" from output of `describe-mode' (bug#38222)

[Juanma Barranquero <lekktu@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1349 bytes --]

On Tue, Nov 19, 2019 at 9:56 PM Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> What I'm suggesting is to look at all the usage we can find and see if
> such a change would break that code.  If none is broken, there's a high
> probability that other code we don't know about wouldn't be
> broken either.

After looking at all the code calling help-split-fundoc in our sources (not
ELPA), I'm unconvinced that changing it to return (nil . DOC) when there's
no usage would be a good idea.

Basically, all callers do the moral equivalent of

(let ((ud (help-split-fundoc documentation symbol)))
   (if ud
       ;;; (car ud) or (cdr ud)

and assume that (car ud) and (cdr ud) are strings.

For example, take a look at this code from
semantic-grammar-eldoc-get-macro-docstring:

    (let* ((doc (help-split-fundoc (documentation expander t) expander)))
      (cond
       (doc
        (setq doc (car doc))
        (string-match "\\`[^ )]* ?" doc)
        (setq doc (concat "(" (substring doc (match-end 0)))))

which would set doc to nil and then try to string-match it.

There are ten cases like this just in our sources; each one would require
some bit of tweaking, however small.

A far less intrusive option IMHO would be to add an optional argument
SECTION, with SECTION = nil as it is now, and SECTION 'usage or 'doc
returning only that part.

[-- Attachment #2: Type: text/html, Size: 1948 bytes --]