On 30/04/18 16:59, Quentin Monnet wrote:
> The Python script used to parse and extract eBPF helpers documentation
> from include/uapi/linux/bpf.h expects a very specific formatting for the
> descriptions (single dots represent a space, '>' stands for a tab):
>
> /*
> ...
> *.int bpf_helper(list of arguments)
> *.> Description
> *.> > Start of description
> *.> > Another line of description
> *.> > And yet another line of description
> *.> Return
> *.> > 0 on success, or a negative error in case of failure
> ...
> */
>
> This is too strict, and painful for developers who wants to add
> documentation for new helpers. Worse, it is extremelly difficult to
> check that the formatting is correct during reviews. Change the
> format expected by the script and make it more flexible. The script now
> works whether or not the initial space (right after the star) is
> present, and accepts both tabs and white spaces (or a combination of
> both) for indenting description sections and contents.
>
> Concretely, something like the following would now be supported:
>
> /*
> ...
> *int bpf_helper(list of arguments)
> *......Description
> *.> > Start of description...
> *> > Another line of description
> *..............And yet another line of description
> *> Return
> *.> ........0 on success, or a negative error in case of failure
> ...
> */
>
> Signed-off-by: Quentin Monnet <quentin.mon...@netronome.com>
> ---
> scripts/bpf_helpers_doc.py | 10 +++++-----
> 1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/scripts/bpf_helpers_doc.py b/scripts/bpf_helpers_doc.py
> index 30ba0fee36e4..717547e6f0a6 100755
> --- a/scripts/bpf_helpers_doc.py
> +++ b/scripts/bpf_helpers_doc.py
> @@ -87,7 +87,7 @@ class HeaderParser(object):
> # - Same as above, with "const" and/or "struct" in front of type
> # - "..." (undefined number of arguments, for bpf_trace_printk())
> # There is at least one term ("void"), and at most five arguments.
> - p = re.compile('^ \* ((.+) \**\w+\((((const )?(struct
> )?(\w+|\.\.\.)( \**\w+)?)(, )?){1,5}\))$')
> + p = re.compile('^ \* ?((.+) \**\w+\((((const )?(struct
> )?(\w+|\.\.\.)( \**\w+)?)(, )?){1,5}\))$')
The proper coding style for such things is to go straight to tabs after
the star and not have the space. So if we're going to make the script
flexible here (and leave coding style enforcement to other tools such
as checkpatch), maybe the regexen should just begin '^ \*\s+' and avoid
relying on counting indentation to delimit sections (e.g. scan for the
section headers like '^ \*\s+Description$' instead).
Btw, leading '^' is unnecessary as re.match() is already implicitly
anchored at start-of-string. (The trailing '$' are still needed.)
-Ed
