tools/lib/python/kdoc/kdoc_output.py

Source file repositories/reference/linux-study-clean/tools/lib/python/kdoc/kdoc_output.py

File Facts

System
Linux kernel
Corpus path
tools/lib/python/kdoc/kdoc_output.py
Extension
.py
Size
34654 bytes
Lines
1161
Domain
Support Tooling And Documentation
Bucket
tools
Inferred role
Support Tooling And Documentation: tools
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-2.0
# Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>.
#
# pylint: disable=C0301,R0902,R0911,R0912,R0913,R0914,R0915,R0917

"""
Classes to implement output filters to print kernel-doc documentation.

The implementation uses a virtual base class ``OutputFormat``. It
contains dispatches to virtual methods, and some code to filter
out output messages.

The actual implementation is done on one separate class per each type
of output, e.g. ``RestFormat`` and ``ManFormat`` classes.

Currently, there are output classes for ReST and man/troff.
"""

import os
import re
from datetime import datetime

from kdoc.kdoc_parser import KernelDoc, type_param
from kdoc.kdoc_re import KernRe


function_pointer = KernRe(r"([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)", cache=False)

# match expressions used to find embedded type information
type_constant = KernRe(r"\b``([^\`]+)``\b", cache=False)
type_constant2 = KernRe(r"\%([-_*\w]+)", cache=False)
type_func = KernRe(r"(\w+)\(\)", cache=False)
type_param_ref = KernRe(r"([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False)

# Special RST handling for func ptr params
type_fp_param = KernRe(r"\@(\w+)\(\)", cache=False)

# Special RST handling for structs with func ptr params
type_fp_param2 = KernRe(r"\@(\w+->\S+)\(\)", cache=False)

type_env = KernRe(r"(\$\w+)", cache=False)
type_enum = KernRe(r"\&(enum\s*([_\w]+))", cache=False)
type_struct = KernRe(r"\&(struct\s*([_\w]+))", cache=False)
type_typedef = KernRe(r"\&(typedef\s*([_\w]+))", cache=False)
type_union = KernRe(r"\&(union\s*([_\w]+))", cache=False)
type_member = KernRe(r"\&([_\w]+)(\.|->)([_\w]+)", cache=False)
type_fallback = KernRe(r"\&([_\w]+)", cache=False)
type_member_func = type_member + KernRe(r"\(\)", cache=False)


class OutputFormat:
    """
    Base class for OutputFormat. If used as-is, it means that only
    warnings will be displayed.
    """

    # output mode.
    OUTPUT_ALL          = 0 #: Output all symbols and doc sections.
    OUTPUT_INCLUDE      = 1 #: Output only specified symbols.
    OUTPUT_EXPORTED     = 2 #: Output exported symbols.
    OUTPUT_INTERNAL     = 3 #: Output non-exported symbols.

    #: Highlights to be used in ReST format.
    highlights = []

    #: Blank line character.
    blankline = ""

    def __init__(self):

Annotation

Implementation Notes