Re: [dpdk-dev] [PATCH v3 3/3] doc/guides: updated script usage for checking patches

[Thomas Monjalon <thomas@monjalon.net>]

02/06/2020 15:53, Ciara Power:
> The contributor's guide includes the usage of both the checkpatches and
> check-git-log scripts, which needed to be updated to reflect the now
> standardised format.

I think the doc update should be merged in the first patch.
In general, doc and code updates should come together.

[...]
>  The script usage is::
>  
> -   checkpatches.sh [-h] [-q] [-v] [patch1 [patch2] ...]]"
> +   checkpatches.sh [-h] [-q] [-v] [-nX|-r range|patch1 [patch2] ...]"
>  
>  Where:
>  
>  * ``-h``: help, usage.
>  * ``-q``: quiet. Don't output anything for files without issues.
>  * ``-v``: verbose.
> +* ``-nX``: the number of commits to check.
> +* ``-r range``: the range to check, range must be a ``git log`` option.
>  * ``patchX``: path to one or more patches.

This is repeating what we get with the -h option.
I would suggest dropping the options explanation from this guide.

>  
>  Then the git logs should be checked using the ``check-git-log.sh`` script.
>  
>  The script usage is::
>  
> -   check-git-log.sh [range]
> +   check-git-log.sh [-h] [-nX|-r range]
>  
> -Where the range is a ``git log`` option.
> +Where:
> +
> +* ``-h``: help, usage.
> +* ``-nX``: the number of commits to check.
> +* ``-r range``: the range to check, range must be a ``git log`` option.

Same here, it is repeating what is documented with using -h.

If we really want to give an indication, we can say once for both that
the -n option is a number of commits from HEAD,
and -r option is a "git log" range.
A single sentence is probably enough.

In general, if we want guides to be read, they must be short.
John, as the doc owner, do you agree?