* bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc
@ 2017-10-10 17:52 Radon Rosborough
2017-10-10 19:24 ` Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Radon Rosborough @ 2017-10-10 17:52 UTC (permalink / raw)
To: 28781
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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc
2017-10-10 17:52 bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc Radon Rosborough
@ 2017-10-10 19:24 ` Eli Zaretskii
2017-10-10 19:44 ` Radon Rosborough
0 siblings, 1 reply; 6+ messages in thread
From: Eli Zaretskii @ 2017-10-10 19:24 UTC (permalink / raw)
To: Radon Rosborough; +Cc: 28781
> From: Radon Rosborough <radon.neon@gmail.com>
> 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."
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc
2017-10-10 19:24 ` Eli Zaretskii
@ 2017-10-10 19:44 ` Radon Rosborough
2017-10-10 20:05 ` Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Radon Rosborough @ 2017-10-10 19:44 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 28781
> 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc
2017-10-10 19:44 ` Radon Rosborough
@ 2017-10-10 20:05 ` Eli Zaretskii
2017-10-10 20:31 ` Radon Rosborough
0 siblings, 1 reply; 6+ messages in thread
From: Eli Zaretskii @ 2017-10-10 20:05 UTC (permalink / raw)
To: Radon Rosborough; +Cc: 28781
> From: Radon Rosborough <radon.neon@gmail.com>
> Date: Tue, 10 Oct 2017 12:44:05 -0700
> Cc: 28781@debbugs.gnu.org
>
> 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc
2017-10-10 20:05 ` Eli Zaretskii
@ 2017-10-10 20:31 ` Radon Rosborough
2017-10-11 13:09 ` Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Radon Rosborough @ 2017-10-10 20:31 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 28781
[-- Attachment #1: Type: text/plain, Size: 211 bytes --]
> > 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.
[-- Attachment #2: 0001-Fix-docstring-style-for-functionp.patch --]
[-- Type: application/octet-stream, Size: 787 bytes --]
From 8cf42f2e59935450fbdadbc6dd8b9ccc564da7cc Mon Sep 17 00:00:00 2001
From: Radon Rosborough <radon.neon@gmail.com>
Date: Tue, 10 Oct 2017 13:28:28 -0700
Subject: [PATCH] Fix docstring style for `functionp'
* src/eval.c (functionp): Make docstring start with verb.
---
src/eval.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/eval.c b/src/eval.c
index acda64e7f0..3f279454b1 100644
--- a/src/eval.c
+++ b/src/eval.c
@@ -2681,7 +2681,7 @@ call8 (Lisp_Object fn, Lisp_Object arg1, Lisp_Object arg2, Lisp_Object arg3,
}
DEFUN ("functionp", Ffunctionp, Sfunctionp, 1, 1, 0,
- doc: /* Non-nil if OBJECT is a function. */)
+ doc: /* Return non-nil if OBJECT is a function. */)
(Lisp_Object object)
{
if (FUNCTIONP (object))
--
2.14.2
^ permalink raw reply related [flat|nested] 6+ messages in thread
* bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc
2017-10-10 20:31 ` Radon Rosborough
@ 2017-10-11 13:09 ` Eli Zaretskii
0 siblings, 0 replies; 6+ messages in thread
From: Eli Zaretskii @ 2017-10-11 13:09 UTC (permalink / raw)
To: Radon Rosborough; +Cc: 28781-done
> From: Radon Rosborough <radon.neon@gmail.com>
> Date: Tue, 10 Oct 2017 13:31:33 -0700
> Cc: 28781@debbugs.gnu.org
>
>
> [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.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2017-10-11 13:09 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2017-10-10 17:52 bug#28781: 25.3; Override erroneous "incorrect verb voice" from checkdoc Radon Rosborough
2017-10-10 19:24 ` Eli Zaretskii
2017-10-10 19:44 ` Radon Rosborough
2017-10-10 20:05 ` Eli Zaretskii
2017-10-10 20:31 ` Radon Rosborough
2017-10-11 13:09 ` Eli Zaretskii
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.