bybrooklyn/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-04-22 08:44:02 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: kdoc_files: 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: <75d58878ad6f83f24f1c0ce9e04301a000ecbaa3.1768838938.git.mchehab+huawei@kernel.org>
This commit is contained in:
Mauro Carvalho Chehab
2026-01-19 17:23:10 +01:00
committed by Jonathan Corbet
parent 4d7f6319fa
commit 8d08c7c6ff
1 changed files with 12 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
tools/lib/python/kdoc/kdoc_files.py
View File

@@ -5,7 +5,8 @@
# pylint: disable=R0903,R0913,R0914,R0917
"""
Parse lernel-doc tags on multiple kernel source files.
Classes for navigating through the files that kernel-doc needs to handle
to generate documentation.
"""
import argparse
@@ -43,7 +44,7 @@ class GlobSourceFiles:
self.srctree = srctree
def _parse_dir(self, dirname):
"""Internal function to parse files recursively"""
"""Internal function to parse files recursively."""
with os.scandir(dirname) as obj:
for entry in obj:
@@ -65,7 +66,7 @@ class GlobSourceFiles:
def parse_files(self, file_list, file_not_found_cb):
"""
Define an iterator to parse all source files from file_list,
handling directories if any
handling directories if any.
"""
if not file_list:
@@ -91,18 +92,18 @@ class KernelFiles():
There are two type of parsers defined here:
- self.parse_file(): parses both kernel-doc markups and
EXPORT_SYMBOL* macros;
- self.process_export_file(): parses only EXPORT_SYMBOL* macros.
``EXPORT_SYMBOL*`` macros;
- self.process_export_file(): parses only ``EXPORT_SYMBOL*`` macros.
"""
def warning(self, msg):
"""Ancillary routine to output a warning and increment error count"""
"""Ancillary routine to output a warning and increment error count."""
self.config.log.warning(msg)
self.errors += 1
def error(self, msg):
"""Ancillary routine to output an error and increment error count"""
"""Ancillary routine to output an error and increment error count."""
self.config.log.error(msg)
self.errors += 1
@@ -128,7 +129,7 @@ class KernelFiles():
def process_export_file(self, fname):
"""
Parses EXPORT_SYMBOL* macros from a single Kernel source file.
Parses ``EXPORT_SYMBOL*`` macros from a single Kernel source file.
"""
# Prevent parsing the same file twice if results are cached
@@ -157,7 +158,7 @@ class KernelFiles():
wcontents_before_sections=False,
logger=None):
"""
Initialize startup variables and parse all files
Initialize startup variables and parse all files.
"""
if not verbose:
@@ -213,7 +214,7 @@ class KernelFiles():
def parse(self, file_list, export_file=None):
"""
Parse all files
Parse all files.
"""
glob = GlobSourceFiles(srctree=self.config.src_tree)
@@ -242,7 +243,7 @@ class KernelFiles():
filenames=None, export_file=None):
"""
Interacts over the kernel-doc results and output messages,
returning kernel-doc markups on each interaction
returning kernel-doc markups on each interaction.
"""
self.out_style.set_config(self.config)