hamza.kesraoui/sst-linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

bpf/scripts: Make description and returns section for helpers/syscalls mandatory

Browse Source 
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>
Signed-off-by: Andrii Nakryiko <andrii@kernel.org>
Reviewed-by: Quentin Monnet <quentin@isovalent.com>
Link: https://lore.kernel.org/bpf/20220119114442.1452088-2-usama.arif@bytedance.com
This commit is contained in:
Usama Arif 2022-01-19 11:44:41 +00:00 committed by Andrii Nakryiko
parent e40fbbf057
commit f1f3f67fd8
1 changed files with 18 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
scripts/bpf_doc.py
View File

@ -92,14 +92,14 @@ class HeaderParser(object):
def parse_element(self): def parse_element(self):
proto = self.parse_symbol() proto = self.parse_symbol()
desc = self.parse_desc() desc = self.parse_desc(proto)
ret = self.parse_ret() ret = self.parse_ret(proto)
return APIElement(proto=proto, desc=desc, ret=ret) return APIElement(proto=proto, desc=desc, ret=ret)
def parse_helper(self): def parse_helper(self):
proto = self.parse_proto() proto = self.parse_proto()
desc = self.parse_desc() desc = self.parse_desc(proto)
ret = self.parse_ret() ret = self.parse_ret(proto)
return Helper(proto=proto, desc=desc, ret=ret) return Helper(proto=proto, desc=desc, ret=ret)
def parse_symbol(self): def parse_symbol(self):
@ -129,16 +129,15 @@ class HeaderParser(object):
self.line = self.reader.readline() self.line = self.reader.readline()
return capture.group(1) return capture.group(1)
def parse_desc(self): def parse_desc(self, proto):
p = re.compile(' \* ?(?:\t| {5,8})Description$') p = re.compile(' \* ?(?:\t| {5,8})Description$')
capture = p.match(self.line) capture = p.match(self.line)
if not capture: if not capture:
# Helper can have empty description and we might be parsing another raise Exception("No description section found for " + proto)
# attribute: return but do not consume.
return ''
# Description can be several lines, some of them possibly empty, and it # Description can be several lines, some of them possibly empty, and it
# stops when another subsection title is met. # stops when another subsection title is met.
desc = '' desc = ''
desc_present = False
while True: while True:
self.line = self.reader.readline() self.line = self.reader.readline()
if self.line == ' *\n': if self.line == ' *\n':
@ -147,21 +146,24 @@ class HeaderParser(object):
p = re.compile(' \* ?(?:\t| {5,8})(?:\t| {8})(.*)') p = re.compile(' \* ?(?:\t| {5,8})(?:\t| {8})(.*)')
capture = p.match(self.line) capture = p.match(self.line)
if capture: if capture:
desc_present = True
desc += capture.group(1) + '\n' desc += capture.group(1) + '\n'
else: else:
break break
if not desc_present:
raise Exception("No description found for " + proto)
return desc return desc
def parse_ret(self): def parse_ret(self, proto):
p = re.compile(' \* ?(?:\t| {5,8})Return$') p = re.compile(' \* ?(?:\t| {5,8})Return$')
capture = p.match(self.line) capture = p.match(self.line)
if not capture: if not capture:
# Helper can have empty retval and we might be parsing another raise Exception("No return section found for " + proto)
# attribute: return but do not consume.
return ''
# Return value description can be several lines, some of them possibly # Return value description can be several lines, some of them possibly
# empty, and it stops when another subsection title is met. # empty, and it stops when another subsection title is met.
ret = '' ret = ''
ret_present = False
while True: while True:
self.line = self.reader.readline() self.line = self.reader.readline()
if self.line == ' *\n': if self.line == ' *\n':
@ -170,9 +172,13 @@ class HeaderParser(object):
p = re.compile(' \* ?(?:\t| {5,8})(?:\t| {8})(.*)') p = re.compile(' \* ?(?:\t| {5,8})(?:\t| {8})(.*)')
capture = p.match(self.line) capture = p.match(self.line)
if capture: if capture:
ret_present = True
ret += capture.group(1) + '\n' ret += capture.group(1) + '\n'
else: else:
break break
if not ret_present:
raise Exception("No return found for " + proto)
return ret return ret
def seek_to(self, target, help_message): def seek_to(self, target, help_message):