xref: /linux/tools/unittests/kdoc-test-schema.yaml (revision 5181afcdf99527dd92a88f80fc4d0d8013e1b510) 
1# SPDX-License-Identifier: GPL-2.0
2# Copyright(c) 2026: Mauro Carvalho Chehab <mchehab@kernel.org>.
3
4# KDoc Test File Schema
5
6# This schema contains objects and properties needed to run kernel-doc
7# self-tests.
8
9$schema: "http://json-schema.org/draft-07/schema#"
10
11tests:
12  type: array
13  minItems: 1
14  description: |
15    A list of kernel-doc tests.
16
17  properties:
18    type: object
19    properties:
20      name:
21        type: string
22        description: |
23          Test name. Should be an unique identifier within the schema.
24          Don't prepend it with "test", as the dynamic test creation will
25          do it.
26
27      description:
28        type: string
29        description: |
30          Test description
31
32      source:
33        type: string
34        description: |
35          C source code that should be parsed by kernel-doc.
36
37      fname:
38        type: string
39        description: |
40          The filename that contains the element.
41          When placing real testcases, please use here the name of
42          the C file (or header) from where the source code was picked.
43
44      exports:
45        type: array
46        items: { type: string }
47        description: |
48          A list of export identifiers that are expected when parsing source.
49
50      expected:
51        type: array
52        minItems: 1
53        description: |
54          A list of expected values. This list consists on objects to check
55          both kdoc_parser and/or kdoc_output objects.
56
57        items:
58          type: object
59          properties:
60            #
61            #  kdoc_item
62            #
63            kdoc_item:
64              type: object
65              description: |
66                Object expected to represent the C source code after parsed
67                by tools/lib/python/kdoc/kdoc_parser.py KernelDoc class.
68                See tools/lib/python/kdoc/kdoc_item.py for its contents.
69
70              properties:
71                name:
72                  type: string
73                  description: |
74                    The name of the identifier (function name, struct name, etc).
75                type:
76                  type: string
77                  description: |
78                    Type of the object, as filled by kdoc_parser. can be:
79                    - enum
80                    - typedef
81                    - union
82                    - struct
83                    - var
84                    - function
85                declaration_start_line:
86                  type: integer
87                  description: |
88                    The line number where the kernel-doc markup started.
89                    The first line of the code is line number 1.
90                sections:
91                  type: object
92                  additionalProperties: { type: string }
93                  description: |
94                    Sections inside the kernel-doc markups:
95                    - "description"
96                    - "return"
97                    - any other part of the markup that starts with "something:"
98                sections_start_lines:
99                  type: object
100                  additionalProperties: { type: integer }
101                  description: |
102                    a list of section names and the starting line of it.
103                parameterlist:
104                  type: array
105                  items: { type: string }
106                  description: |
107                    Ordered list of parameter names.
108
109                parameterdesc_start_lines:
110                  type: object
111                  additionalProperties: { type: integer }
112                  description: |
113                    Mapping from parameter name to the line where its
114                    description starts.
115                parameterdescs:
116                  type: object
117                  additionalProperties: { type: string }
118                  description: |
119                    Mapping from parameter name to its description.
120
121                parametertypes:
122                  type: object
123                  additionalProperties: { type: string }
124                  description: |
125                    Mapping from parameter name to its type.
126
127                other_stuff:
128                  type: object
129                  additionalProperties: {}
130                  description: |
131                    Extra properties that will be stored at the item.
132                    Should match what kdoc_output expects.
133
134              required:
135                - name
136                - type
137                - declaration_start_line
138
139            rst:
140              type: string
141              description: |
142                The expected output for RestOutput class.
143
144            man:
145              type: string
146              description: |
147                The expected output for ManOutput class.
148
149        anyOf:
150          required: kdoc_item
151          required: source
152
153    required:
154      - name
155      - fname
156      - expected
157