bug#35230: char-displayable-p return code is conflictingly documented

[Robert Pluim <rpluim@gmail.com>]

(This comes as a result of the stackexchange question at
https://emacs.stackexchange.com/questions/48810)

char-displayable-p docstring says

     Return non-nil if we should be able to display CHAR.

The elisp manual says something subtly different:

     This function returns ‘t’ if Emacs ought to be able to display
     CHAR.  More precisely, if the selected frame’s fontset has a font
     to display the character set that CHAR belongs to.

The function itself is more in line with the docstring:

(char-displayable-p #xE01EF) => unicode

since I donʼt have a font with a glyph for that character, so it ends
up displayed as a box with the unicode code point inside it. The code
that results in 'unicode has the comment 	     

    ;; On a text terminal without glyph codes, CHAR is displayable
    ;; if the coding system for the terminal can encode it.

but Iʼm very much on a graphical terminal here, not a text terminal.

For comparison, when I do have a font:

(char-displayable-p #x2502) => <font-object
"-*-Menlo-normal-normal-normal-*-12-*-*-*-m-0-iso10646-1">

The question is: what should the docstring/manual say? The original
intent of char-displayable-p seems to be as a wrapper around
internal-char-font to allow asking "do I have a glyph for this
character", but thatʼs not what it does today.

Robert