> 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 _______________________________________________ emacs-pretest-bug mailing list [email protected] http://lists.gnu.org/mailman/listinfo/emacs-pretest-bug
