From: Usama Arif <usama.arif@bytedance.com>
To: bpf@vger.kernel.org
Cc: ast@kernel.org, daniel@iogearbox.net, fam.zheng@bytedance.com,
cong.wang@bytedance.com, song@kernel.org, quentin@isovalent.com,
andrii.nakryiko@gmail.com, Usama Arif <usama.arif@bytedance.com>
Subject: [PATCH bpf-next v3 2/3] bpf/scripts: Make description and returns section for helpers/syscalls mandatory
Date: Wed, 19 Jan 2022 11:44:41 +0000 [thread overview]
Message-ID: <20220119114442.1452088-2-usama.arif@bytedance.com> (raw)
In-Reply-To: <20220119114442.1452088-1-usama.arif@bytedance.com>
This enforce a minimal formatting consistency for the documentation. The
description and returns missing for a few helpers have also been added.
Signed-off-by: Usama Arif <usama.arif@bytedance.com>
Reviewed-by: Quentin Monnet <quentin@isovalent.com>
---
v1->v3:
- Moved UAPI header changes to a seperate commit (suggested by
Andrii Nakryiko)
---
scripts/bpf_doc.py | 30 ++++++++++++++++++------------
1 file changed, 18 insertions(+), 12 deletions(-)
diff --git a/scripts/bpf_doc.py b/scripts/bpf_doc.py
index 5cf8ae2e72bd..20441e5d2d33 100755
--- a/scripts/bpf_doc.py
+++ b/scripts/bpf_doc.py
@@ -92,14 +92,14 @@ class HeaderParser(object):
def parse_element(self):
proto = self.parse_symbol()
- desc = self.parse_desc()
- ret = self.parse_ret()
+ desc = self.parse_desc(proto)
+ ret = self.parse_ret(proto)
return APIElement(proto=proto, desc=desc, ret=ret)
def parse_helper(self):
proto = self.parse_proto()
- desc = self.parse_desc()
- ret = self.parse_ret()
+ desc = self.parse_desc(proto)
+ ret = self.parse_ret(proto)
return Helper(proto=proto, desc=desc, ret=ret)
def parse_symbol(self):
@@ -129,16 +129,15 @@ class HeaderParser(object):
self.line = self.reader.readline()
return capture.group(1)
- def parse_desc(self):
+ def parse_desc(self, proto):
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
- # attribute: return but do not consume.
- return ''
+ raise Exception("No description section found for " + proto)
# Description can be several lines, some of them possibly empty, and it
# stops when another subsection title is met.
desc = ''
+ desc_present = False
while True:
self.line = self.reader.readline()
if self.line == ' *\n':
@@ -147,21 +146,24 @@ class HeaderParser(object):
p = re.compile(' \* ?(?:\t| {5,8})(?:\t| {8})(.*)')
capture = p.match(self.line)
if capture:
+ desc_present = True
desc += capture.group(1) + '\n'
else:
break
+
+ if not desc_present:
+ raise Exception("No description found for " + proto)
return desc
- def parse_ret(self):
+ def parse_ret(self, proto):
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
- # attribute: return but do not consume.
- return ''
+ raise Exception("No return section found for " + proto)
# Return value description can be several lines, some of them possibly
# empty, and it stops when another subsection title is met.
ret = ''
+ ret_present = False
while True:
self.line = self.reader.readline()
if self.line == ' *\n':
@@ -170,9 +172,13 @@ class HeaderParser(object):
p = re.compile(' \* ?(?:\t| {5,8})(?:\t| {8})(.*)')
capture = p.match(self.line)
if capture:
+ ret_present = True
ret += capture.group(1) + '\n'
else:
break
+
+ if not ret_present:
+ raise Exception("No return found for " + proto)
return ret
def seek_to(self, target, help_message):
--
2.25.1
next prev parent reply other threads:[~2022-01-19 11:44 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-01-19 11:44 [PATCH bpf-next v3 1/3] uapi/bpf: Add missing description and returns for helper documentation Usama Arif
2022-01-19 11:44 ` Usama Arif [this message]
2022-01-19 11:44 ` [PATCH bpf-next v3 3/3] bpf/scripts: Raise an exception if the correct number of sycalls are not generated Usama Arif
2022-01-19 18:40 ` [PATCH bpf-next v3 1/3] uapi/bpf: Add missing description and returns for helper documentation patchwork-bot+netdevbpf
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220119114442.1452088-2-usama.arif@bytedance.com \
--to=usama.arif@bytedance.com \
--cc=andrii.nakryiko@gmail.com \
--cc=ast@kernel.org \
--cc=bpf@vger.kernel.org \
--cc=cong.wang@bytedance.com \
--cc=daniel@iogearbox.net \
--cc=fam.zheng@bytedance.com \
--cc=quentin@isovalent.com \
--cc=song@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.