github-mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-05-31 10:33:41 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity Graph

docs: kdoc: enrich_formatter: Improve docstrings and comments

Browse Source 
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>
This commit is contained in:
Mauro Carvalho Chehab 2026-01-19 17:23:16 +01:00 committed by Jonathan Corbet
parent e68c84b9f3
commit 7ef684c9fd
1 changed files with 15 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
tools/lib/python/kdoc/enrich_formatter.py
View File

@ -26,12 +26,16 @@ class EnrichFormatter(argparse.HelpFormatter):
and how they're used at the __doc__ description.
"""
def __init__(self, *args, **kwargs):
"""Initialize class and check if is TTY"""
"""
Initialize class and check if is TTY.
"""
super().__init__(*args, **kwargs)
self._tty = sys.stdout.isatty()
def enrich_text(self, text):
"""Handle ReST markups (currently, only ``foo``)"""
r"""
Handle ReST markups (currently, only \`\`text\`\` markups).
"""
if self._tty and text:
# Replace ``text`` with ANSI SGR (bold)
return re.sub(r'\`\`(.+?)\`\`',
@ -39,12 +43,16 @@ class EnrichFormatter(argparse.HelpFormatter):
return text
def _fill_text(self, text, width, indent):
"""Enrich descriptions with markups on it"""
"""
Enrich descriptions with markups on it.
"""
enriched = self.enrich_text(text)
return "\n".join(indent + line for line in enriched.splitlines())
def _format_usage(self, usage, actions, groups, prefix):
"""Enrich positional arguments at usage: line"""
"""
Enrich positional arguments at usage: line.
"""
prog = self._prog
parts = []
@ -63,7 +71,9 @@ class EnrichFormatter(argparse.HelpFormatter):
return usage_text
def _format_action_invocation(self, action):
"""Enrich argument names"""
"""
Enrich argument names.
"""
if not action.option_strings:
return self.enrich_text(f"``{action.dest.upper()}``")