[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: read-face-name doc string incorrect
From: |
Nick Roberts |
Subject: |
Re: read-face-name doc string incorrect |
Date: |
Sun, 25 Jun 2006 16:24:24 +1200 |
> The doc string for read-face-name says this:
>
> Read a face, defaulting to the face or faces on the char after point.
> If it has a `read-face-name' property, that overrides the `face' property.
> prompt describes what you will do with the face (don't end in a space).
> string-describing-default describes what default you will use
> if this function returns nil.
> If multiple is non-nil, return a list of faces (possibly only one).
> Otherwise, return a single face.
>
> The part about "if this function returns nil" is incorrect. The
> function never returns nil - it returns a non-empty list of faces or a
> single face. This should say something to the effect of "if the user
> just hits RET".
It does return nil e.g with customize-face when the user hits RET. It
wouldn't make sense to say "if the user just hits RET" for read-face-name
because it's not an interactive function. I agree that it's not clear from
the doc string what read-face-name returns.
The phrase "If it has a `read-face-name' property," appears as a link to
the function read-face-name so perhaps it could be rewritten as:
If it has the property `read-face-name',...
and help-xref-symbol-regexp modified by replacing "\\(symbol\\|program\\)\\|"
with "\\(symbol\\|program\\|property\\)\\|".
> The prompt and default-string are not clear, in any case, especially
> the part about describing what you will do with the face and not
> ending in a space. The doc string must give an example, or no one will
> understand what kind of prompt string and default-string arguments to
> use.
I think the elisp manual is the right place for examples but I don't think
read-face-name is described there. But then it's not used much either.
--
Nick http://www.inet.net.nz/~nickrob