bpf: relax constraints on formatting for eBPF helper documentation
authorQuentin Monnet <quentin.monnet@netronome.com>
Wed, 2 May 2018 13:20:24 +0000 (14:20 +0100)
committerDaniel Borkmann <daniel@iogearbox.net>
Wed, 2 May 2018 15:46:50 +0000 (17:46 +0200)
commit6f96674dbd8ca659769f1c65ca15638e50b69341
treec755dc183829afcd09f9988a52da26842801b5c6
parenta2c7a98301d9f9bcfc4244de04252a04c0b68a79
bpf: relax constraints on formatting for eBPF helper documentation

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 dot represents 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 extremely 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
     ...
     */

While at it, remove unnecessary carets from each regex used with match()
in the script. They are redundant, as match() tries to match from the
beginning of the string by default.

v2: Remove unnecessary caret when a regex is used with match().

Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com>
Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
scripts/bpf_helpers_doc.py