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.