Re: checkdoc (was: mh-e 6.2 imminent)

[Miles Bader]

On Tue, Oct 29, 2002 at 12:19:13AM +0100, Kim F. Storm wrote:
> Try to find all uses of the region and mouse faces...  I bet that you
> get numerous false hits that you wouldn't have got had they been named
> region-face and mouse-face.  

Because of the property I've already noted -- that uses of constant faces
almost always occur in contexts where the use of a face is _explicit_,
e.g. accompanying a variable or function called `...-face' -- I can do this:

  grep "face.*'region" ...

which in fact works quite well.

One way you can test this is to pick some existing face called `foo-face',
and grep for both "foo-face" and "face.*foo" in the sources.  It's best to
pick a face that _doesn't_ have an identically-named variable, because
otherwise you tend to get lots of false hits in the `foo-face' case

[this is a problem, incidentally, with faces like `foo-face' -- code such as
font-lock tends to be even more confusing because there are _identical_
symbols being used for both variables and faces, in ways that are not that
easy to distinguish at first glance; I think it would actually be _more_
clear if only the variables were called `foo-face']

Here's an example:

First using the `-face' suffix:

   grep -nH "gnus-cite-attribution-face" lisp/gnus/*.el
   lisp/gnus/gnus-cite.el:126:(defface gnus-cite-attribution-face '((t
   lisp/gnus/gnus-cite.el:130:(defcustom gnus-cite-attribution-face 
'gnus-cite-attribution-face
   lisp/gnus/gnus-cite.el:317:corresponding citation merged with 
`gnus-cite-attribution-face'.
   lisp/gnus/gnus-cite.el:367:  (gnus-cite-add-face number skip 
gnus-cite-attribution-face))
   lisp/gnus/gnus-cite.el:375:  (gnus-cite-add-face number skip 
gnus-cite-attribution-face)))))

Now without it:

   grep -nH "face.*gnus-cite-attribution" lisp/gnus/*.el
   lisp/gnus/gnus-cite.el:126:(defface gnus-cite-attribution-face '((t
   lisp/gnus/gnus-cite.el:130:(defcustom gnus-cite-attribution-face 
'gnus-cite-attribution-face
   lisp/gnus/gnus-cite.el:367:  (gnus-cite-add-face number skip 
gnus-cite-attribution-face))
   lisp/gnus/gnus-cite.el:375:  (gnus-cite-add-face number skip 
gnus-cite-attribution-face)))))

Note that the second catches all the same cases except a mention in a
doc-string.

-Miles
-- 
Come now, if we were really planning to harm you, would we be waiting here, 
 beside the path, in the very darkest part of the forest?