xref: /linux/tools/lib/python/kdoc/kdoc_item.py (revision 99ec67a9984fdf38c7ed78695aeb1b99cfee5b50) 
1# SPDX-License-Identifier: GPL-2.0
2#
3# A class that will, eventually, encapsulate all of the parsed data that we
4# then pass into the output modules.
5#
6
7"""
8Data class to store a kernel-doc Item.
9"""
10
11class KdocItem:
12    """
13    A class that will, eventually, encapsulate all of the parsed data that we
14    then pass into the output modules.
15    """
16
17    def __init__(self, name, fname, type, start_line,
18                 **other_stuff):
19        self.name = name
20        self.fname = fname
21        self.type = type
22        self.declaration_start_line = start_line
23        self.sections = {}
24        self.sections_start_lines = {}
25        self.parameterlist = []
26        self.parameterdesc_start_lines = {}
27        self.parameterdescs = {}
28        self.parametertypes = {}
29
30        self.warnings = []
31
32        #
33        # Just save everything else into our own dict so that the output
34        # side can grab it directly as before.  As we move things into more
35        # structured data, this will, hopefully, fade away.
36        #
37        known_keys = {
38            'declaration_start_line',
39            'sections',
40            'sections_start_lines',
41            'parameterlist',
42            'parameterdesc_start_lines',
43            'parameterdescs',
44            'parametertypes',
45            'warnings',
46        }
47
48        self.other_stuff = {}
49        for k, v in other_stuff.items():
50            if k in known_keys:
51                setattr(self, k, v)           # real attribute
52            else:
53                self.other_stuff[k] = v
54
55    def get(self, key, default = None):
56        """
57        Get a value from optional keys.
58        """
59        return self.other_stuff.get(key, default)
60
61    def __getitem__(self, key):
62        return self.get(key)
63
64    def __repr__(self):
65        return f"KdocItem({self.name}, {self.fname}, {self.type}, {self.declaration_start_line})"
66
67    @classmethod
68    def from_dict(cls, d):
69        """Create a KdocItem from a plain dict."""
70
71        cp = d.copy()
72        name        = cp.pop('name', None)
73        fname       = cp.pop('fname', None)
74        type        = cp.pop('type', None)
75        start_line  = cp.pop('start_line', 1)
76        other_stuff = cp.pop('other_stuff', {})
77
78        # Everything that’s left goes straight to __init__
79        return cls(name, fname, type, start_line, **cp, **other_stuff)
80
81    #
82    # Tracking of section and parameter information.
83    #
84    def set_sections(self, sections, start_lines):
85        """
86        Set sections and start lines.
87        """
88        self.sections = sections
89        self.sections_start_lines = start_lines
90
91    def set_params(self, names, descs, types, starts):
92        """
93        Set parameter list: names, descriptions, types and start lines.
94        """
95        self.parameterlist = names
96        self.parameterdescs = descs
97        self.parametertypes = types
98        self.parameterdesc_start_lines = starts
99