bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc

Radon Rosborough
I have the following definition:

    (defmacro straight--functionp (object)
      "Non-nil if OBJECT, an unquoted symbol, evaluates to a function.
    However, if OBJECT evaluates to its own symbol value or t, then
    return nil. This is useful for allowing a function to be called
    with nil, non-nil, or a function object, without worrying about
    the non-nil value being interpreted as a function: just call the
    function with the quoted name of the argument, or use t."
      (let ((object-sym (make-symbol "object")))
        `(let ((,object-sym ,object))
           (and (not (memq ,object-sym '(,object t)))
                (functionp ,object-sym)))))

M-x checkdoc reports the following on the first line:

    Probably "evaluates" should be imperative "evaluate"

This is wrong. How can I suppress this spurious warning, other than by
rewording the docstring? I know that checkdoc has
`checkdoc-symbol-words' for suppressing spurious warnings about unquoted
symbols, but there appears to be nothing similar I can customize in
file-local variables for this case.



Reply | Threaded
Open this post in threaded view
|

bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc

Eli Zaretskii
> From: Radon Rosborough <[hidden email]>
> Date: Tue, 10 Oct 2017 10:52:18 -0700
>
> I have the following definition:
>
>     (defmacro straight--functionp (object)
>       "Non-nil if OBJECT, an unquoted symbol, evaluates to a function.

Try

    "Return non-nil if OBJECT, an unquoted symbol, evaluates to a function."

Or even

    "Return non-nil if OBJECT, evaluates to a function.
  OBJECT should be an unquoted symbol."



Reply | Threaded
Open this post in threaded view
|

bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc

Radon Rosborough
> Try
>
>     "Return non-nil if OBJECT, an unquoted symbol, evaluates to a
>     function."

That makes sense. Is it recommended to have all function docstrings
start with a verb? If so, maybe the docstring for `functionp' should
be changed (after all, it was what I modeled this one off of):

    Non-nil if OBJECT is a function.



Reply | Threaded
Open this post in threaded view
|

bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc

Eli Zaretskii
> From: Radon Rosborough <[hidden email]>
> Date: Tue, 10 Oct 2017 12:44:05 -0700
> Cc: [hidden email]
>
> Is it recommended to have all function docstrings start with a verb?

Yes.  From the ELisp manual, node "Documentation Tips"

     For a function, the first line should briefly answer the question,
     “What does this function do?” For a variable, the first line should
     briefly answer the question, “What does this value mean?”

(It talks about the first line of the doc string.)

> If so, maybe the docstring for `functionp' should be changed (after
> all, it was what I modeled this one off of):
>
>     Non-nil if OBJECT is a function.

Yes, I think so.



Reply | Threaded
Open this post in threaded view
|

bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc

Radon Rosborough
> > If so, maybe the docstring for `functionp' should be changed (after
> > all, it was what I modeled this one off of):
> >
> >     Non-nil if OBJECT is a function.
>
> Yes, I think so.

The patch is attached.

0001-Fix-docstring-style-for-functionp.patch (1K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc

Eli Zaretskii
> From: Radon Rosborough <[hidden email]>
> Date: Tue, 10 Oct 2017 13:31:33 -0700
> Cc: [hidden email]
>
>
> [1:text/plain Hide]
>
> > > If so, maybe the docstring for `functionp' should be changed (after
> > > all, it was what I modeled this one off of):
> > >
> > >     Non-nil if OBJECT is a function.
> >
> > Yes, I think so.
>
> The patch is attached.

Thanks, pushed.