3

The docstring of the following function doesn't make Emacs happy:

(defun foo-all-the-bars ()
  "Foo all the bars.
Starts by fooing some bars by enabling `prettify-symbols-mode',
then manually foos any remaining bars."
  (prettify-symbols-mode))

Checkdoc complains with the following message:

Disambiguate prettify-symbols-mode by preceding w/ function,command,variable,option or symbol.

Which one should I use?

1

If any I would use "function" because the proper documentation of a minor mode is in its function docstring.

Personally I tend to ignore this particular checkdoc warning.

| improve this answer | |
1

One way to disambiguate:

(defun foo-all-the-bars ()
  "Foo all the bars.
Starts by fooing some bars by enabling the command `prettify-symbols-mode',
then manually foos any remaining bars."
  (prettify-symbols-mode))

Instead of command, you can use function, variable, option, or symbol as the checkdoc string suggests. In any case, this is not a lisp syntactic requirement but a grammar style suggested by checkdoc for doc strings.

| improve this answer | |
  • 1
    Is that true? I thought that this prefix was used to decide what to target to use for the link in the docs, so it wouldn't be just grammar style. – Clément Dec 19 '15 at 17:13
  • Perhaps there are other incidental benefits. – Emacs User Dec 19 '15 at 17:25

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.