Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kdoc: enrich_formatter: Improve docstrings and comments
In preparation to document kernel-doc module, improve its
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <55ec8b896fe00529d326859cd094230fb5a2cd30.1768838938.git.mchehab+huawei@kernel.org>
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
7ef684c9
e68c84b9
+15
-5
+15
-5
tools/lib/python/kdoc/enrich_formatter.py
+15
-5
tools/lib/python/kdoc/enrich_formatter.py
···
26
26
and how they're used at the __doc__ description.
27
27
"""
28
28
def __init__(self, *args, **kwargs):
29
-
"""Initialize class and check if is TTY"""
29
+
"""
30
+
Initialize class and check if is TTY.
31
+
"""
30
32
super().__init__(*args, **kwargs)
31
33
self._tty = sys.stdout.isatty()
32
34
33
35
def enrich_text(self, text):
34
-
"""Handle ReST markups (currently, only ``foo``)"""
36
+
r"""
37
+
Handle ReST markups (currently, only \`\`text\`\` markups).
38
+
"""
35
39
if self._tty and text:
36
40
# Replace ``text`` with ANSI SGR (bold)
37
41
return re.sub(r'\`\`(.+?)\`\`',
···
43
39
return text
44
40
45
41
def _fill_text(self, text, width, indent):
46
-
"""Enrich descriptions with markups on it"""
42
+
"""
43
+
Enrich descriptions with markups on it.
44
+
"""
47
45
enriched = self.enrich_text(text)
48
46
return "\n".join(indent + line for line in enriched.splitlines())
49
47
50
48
def _format_usage(self, usage, actions, groups, prefix):
51
-
"""Enrich positional arguments at usage: line"""
49
+
"""
50
+
Enrich positional arguments at usage: line.
51
+
"""
52
52
53
53
prog = self._prog
54
54
parts = []
···
71
63
return usage_text
72
64
73
65
def _format_action_invocation(self, action):
74
-
"""Enrich argument names"""
66
+
"""
67
+
Enrich argument names.
68
+
"""
75
69
if not action.option_strings:
76
70
return self.enrich_text(f"``{action.dest.upper()}``")
77
71