Re: [PATCH 1/6] scripts/coccinelle: add error-use-after-free.cocci

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Tue, 31 Mar 2020 at 10:01, Markus Armbruster <armbru@redhat.com> wrote:
>> I doubt including basic spatch instructions with every script is a good
>> idea.  Better explain it in one place, with proper maintenance.
>> scripts/coccinelle/README?  We could be a bit more verbose there,
>> e.g. to clarify required vs. suggested options.
>
> I find it useful -- you (hopefully) get the actual command line
> the original author used, rather than having to guess which
> options might be significant. (eg the last one I added uses
> --keep-comments --smpl-spacing --include-headers --dir target
> which aren't all always used but which do all matter here for
> getting the change that went in in the commit that used the script.)
> Most of us use coccinelle as an occasional tool, not an
> everyday one, so not having to look through the docs to figure
> out the right rune is a benefit, even for the options that
> we do use on pretty much every spatch run.

Generic instructions for using .cocci scripts should go into README.
Enough to get you started if you know nothing about Coccinelle.

Options that should always be used with a certain script should be
documented in that script.

Options that only affect work-flow, not the patch, I'd rather keep out
of the script.  If there are any we feel we should mention, do that in
README.  Example: --no-show-diff.

Brief instructions for how a patch was created should be included in the
commit message.  They should suffice for readers familiar with
Coccinelle.  Yes, there's a bit of redundancy with README and the
script.