Message ID | 20180517124356.1452-1-quentin.monnet@netronome.com |
---|---|
State | Accepted, archived |
Delegated to: | BPF Maintainers |
Headers | show |
Series | [bpf-next] bpf: change eBPF helper doc parsing script to allow for smaller indent | expand |
On 05/17/2018 02:43 PM, Quentin Monnet wrote: > Documentation for eBPF helpers can be parsed from bpf.h and eventually > turned into a man page. Commit 6f96674dbd8c ("bpf: relax constraints on > formatting for eBPF helper documentation") changed the script used to > parse it, in order to allow for different indent style and to ease the > work for writing documentation for future helpers. > > The script currently considers that the first tab can be replaced by 6 > to 8 spaces. But the documentation for bpf_fib_lookup() uses a mix of > tabs (for the "Description" part) and of spaces ("Return" part), and > only has 5 space long indent for the latter. > > We probably do not want to change the values accepted by the script each > time a new helper gets a new indent style. However, it is worth noting > that with those 5 spaces, the "Description" and "Return" part *look* > aligned in the generated patch and in `git show`, so it is likely other > helper authors will use the same length. Therefore, allow for helper > documentation to use 5 spaces only for the first indent level. > > Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Applied to bpf-next, thanks Quentin! Btw in the current uapi description some of the helpers have a new line before 'Return' and most have not. I presume it doesn't really matter though we might want to do a one-time cleanup on these cases at some point in time.
2018-05-17 17:38 UTC+0200 ~ Daniel Borkmann <daniel@iogearbox.net> > On 05/17/2018 02:43 PM, Quentin Monnet wrote: >> Documentation for eBPF helpers can be parsed from bpf.h and eventually >> turned into a man page. Commit 6f96674dbd8c ("bpf: relax constraints on >> formatting for eBPF helper documentation") changed the script used to >> parse it, in order to allow for different indent style and to ease the >> work for writing documentation for future helpers. >> >> The script currently considers that the first tab can be replaced by 6 >> to 8 spaces. But the documentation for bpf_fib_lookup() uses a mix of >> tabs (for the "Description" part) and of spaces ("Return" part), and >> only has 5 space long indent for the latter. >> >> We probably do not want to change the values accepted by the script each >> time a new helper gets a new indent style. However, it is worth noting >> that with those 5 spaces, the "Description" and "Return" part *look* >> aligned in the generated patch and in `git show`, so it is likely other >> helper authors will use the same length. Therefore, allow for helper >> documentation to use 5 spaces only for the first indent level. >> >> Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> > > Applied to bpf-next, thanks Quentin! Btw in the current uapi description > some of the helpers have a new line before 'Return' and most have not. I > presume it doesn't really matter though we might want to do a one-time > cleanup on these cases at some point in time. Thanks Daniel! I did notice those new lines as well. The script was failing on the 5-space indent, but not on the new lines, so I let them as they are. I agree for the cleanup, I can send a patch when the various helpers currently being discussed on the list are merged. Best, Quentin
diff --git a/scripts/bpf_helpers_doc.py b/scripts/bpf_helpers_doc.py index 8f59897fbda1..5010a4d5bfba 100755 --- a/scripts/bpf_helpers_doc.py +++ b/scripts/bpf_helpers_doc.py @@ -95,7 +95,7 @@ class HeaderParser(object): return capture.group(1) def parse_desc(self): - p = re.compile(' \* ?(?:\t| {6,8})Description$') + p = re.compile(' \* ?(?:\t| {5,8})Description$') capture = p.match(self.line) if not capture: # Helper can have empty description and we might be parsing another @@ -109,7 +109,7 @@ class HeaderParser(object): if self.line == ' *\n': desc += '\n' else: - p = re.compile(' \* ?(?:\t| {6,8})(?:\t| {8})(.*)') + p = re.compile(' \* ?(?:\t| {5,8})(?:\t| {8})(.*)') capture = p.match(self.line) if capture: desc += capture.group(1) + '\n' @@ -118,7 +118,7 @@ class HeaderParser(object): return desc def parse_ret(self): - p = re.compile(' \* ?(?:\t| {6,8})Return$') + p = re.compile(' \* ?(?:\t| {5,8})Return$') capture = p.match(self.line) if not capture: # Helper can have empty retval and we might be parsing another @@ -132,7 +132,7 @@ class HeaderParser(object): if self.line == ' *\n': ret += '\n' else: - p = re.compile(' \* ?(?:\t| {6,8})(?:\t| {8})(.*)') + p = re.compile(' \* ?(?:\t| {5,8})(?:\t| {8})(.*)') capture = p.match(self.line) if capture: ret += capture.group(1) + '\n'
Documentation for eBPF helpers can be parsed from bpf.h and eventually turned into a man page. Commit 6f96674dbd8c ("bpf: relax constraints on formatting for eBPF helper documentation") changed the script used to parse it, in order to allow for different indent style and to ease the work for writing documentation for future helpers. The script currently considers that the first tab can be replaced by 6 to 8 spaces. But the documentation for bpf_fib_lookup() uses a mix of tabs (for the "Description" part) and of spaces ("Return" part), and only has 5 space long indent for the latter. We probably do not want to change the values accepted by the script each time a new helper gets a new indent style. However, it is worth noting that with those 5 spaces, the "Description" and "Return" part *look* aligned in the generated patch and in `git show`, so it is likely other helper authors will use the same length. Therefore, allow for helper documentation to use 5 spaces only for the first indent level. Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> --- scripts/bpf_helpers_doc.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)