Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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