CoCalc -- kdoc-test-schema.yaml

GitHub Repository: torvalds/linux
Path: blob/master/tools/unittests/kdoc-test-schema.yaml
¹⁷⁰⁸³¹ views
1
# SPDX-License-Identifier: GPL-2.0
2
# Copyright(c) 2026: Mauro Carvalho Chehab <[email protected]>.
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

11
tests:
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

158
Product

Resources

Company
