bug#6598: Documentation: progmodes/grep.el -- numerous errors ommissions and opportunities for improvement.

[Lars Ingebrigtsen <larsi@gnus.org>]

MON KEY <monkey@sandpframing.com> writes:

> Documentation progmodes/grep.el -- numerous errors ommissions and
> opportunities for improvement.
>
> --
> There are 13 docstring references of the form: `grep-compute-defaults'
> in progmodes/grep.el and 7 more in lisp/loaddefs.el including the
> grep-compute-defaults autoload yet the function itself is not
> documented.

OK, added.

> -- 
> The following functions accept a CONFIRM argument:
> `lgrep', `rgrep', `zrgrep'
>
> There is no explicit documentation of the CONFIRM parameter in any of
> the docstrings for these functions.

Ditto.

> Likewise, `grep', `lgrep', `rgrep', `grep-find' docs have the
> following two vacuous statements:
>
>  "[Cc]ollect output in a buffer."
>   "in the grep output buffer"
>
> but do not specify which buffer e.g. the default: "*grep*".

Ditto.

> The constant `grep-expand-keywords' has the typo:
>
>  "If car of an element matches, the cdr is evalled in to get the"
>                                                      ^
> Should probably be: "in order to"
>
> Also, the doc makes mention that one should
>  "Note dynamic scoping of variables."
>
> but doesn't discuss what these variables are, nor why they should be
> noted.

I've now rephrased it and documented the variables.

> --
> The function `grep-expand-template' uses the term "Patch":
>
>  "Patch grep COMMAND string replacing <C>, <D>, <F>, <R>, and <X>."
>
> This terminology should be avoided b/c it conflates with diff's `patch'.
> Likewise, it isn't clear what is getting replaced by the "patch".

I used "expand" instead.

> --
> The function `grep-read-files' does not document the REGEXP parameter.

Fixed.

> The variable `grep-find-ignored-directories' should indicate that it
> defaults to the value of the variable `vc-directory-exclusion-list' as
> this is an option that is user customizable it may be useful to simply
> modify the value of that variable instead.

Fixed.

> The variables `grep-template', `grep-find-template',
> `grep-highlight-matches', `grep-find-command', `grep-use-null-device'
> say:
>
>  " {...} to change the default value, use Customize or call the function
>    `grep-apply-setting'."
>
> "Customize" should be: "\\[customize]"

Fixed.

> Likewise, where this is a customizable variable and the intent seems
> to be that the user _customize_ them the sentence:
>
>  "You can customize this variable."
>
> is already present at the bottom of each of these function's
> docstrings.

I'm guessing the intent here is to say that you can use
`grep-apply-setting' instead of Customize, so I think the repetition is OK.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no