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

[Kim F. Storm]

Miles Bader <address@hidden> writes:

> 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.

But fails if face and region are on different lines...

> 
> 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

I think it is a matter of taste whether those identically named
variables are false hits.

> 
> [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.

I don't have problems separating those in general -- a face is usually
quoted, a variable is not.


I think somebody else should express their opinions -- as you and I
obviously cannot agree on this (IMHO non-)issue.

-- 
Kim F. Storm <address@hidden> http://www.cua.dk