xref: /linux/tools/unittests/kdoc-test.yaml (revision 01d6d7bf9672f1aeabbffaa3fbfb8017223ff878) 
1# SPDX-License-Identifier: GPL-2.0
2# Copyright (c) 2026: Mauro Carvalho Chehab <mchehab@kernel.org>
3
4# Test cases for the dynamic tests.
5# Useful to test if kernel-doc classes are doing what it is expected.
6#
7
8tests:
9- name: func1
10  fname: mock_functions.c
11  description: "Simplest function test: do nothing, just rst output"
12
13  source: |
14    /**
15      * func1 - Not exported function
16      * @arg1: @arg1 does nothing
17      *
18      * Does nothing
19      *
20      * return:
21      *    always return 0.
22      */
23    int func1(char *arg1) { return 0; };
24
25
26  expected:
27  - rst: |
28    .. c:function:: int func1 (char *arg1)
29
30      Not exported function
31
32    .. container:: kernelindent
33
34      **Parameters**
35
36      ``char *arg1``
37        **arg1** does nothing
38
39      **Description**
40
41      Does nothing
42
43      **Return**
44
45      always return 0.
46
47    # TODO: how to handle timestamps at .TH?
48    man: |
49      .TH "func1" 9 "February 2026"  "" "Kernel API Manual"
50      .SH NAME
51      func1 \- Not exported function
52      .SH SYNOPSIS
53      .B "int" func1
54      .BI "(char *arg1 "  ");"
55      .SH ARGUMENTS
56      .IP "arg1" 12
57      \fIarg1\fP does nothing
58      .SH "DESCRIPTION"
59      Does nothing
60      .SH "RETURN"
61      always return 0.
62      .SH "SEE ALSO"
63      .PP
64      Kernel file \fBmock_functions.c\fR
65
66- name: func2
67  fname: func2.c
68  description: Simple test with exports
69
70  source: |
71    /**
72      * func2() - Exported function
73      * @arg1: @arg1 does nothing
74      *
75      * Does nothing
76      *
77      * return:
78      *    always return 0.
79      */
80    int func2(char *arg1) { return 0; };
81    EXPORT_SYMBOL(func2);
82
83  exports: func2
84  expected:
85  - kdoc_item:
86      name: func2
87      type: function
88      declaration_start_line: 1
89
90      sections:
91        Description: |
92          Does nothing
93
94        Return: |
95          always return 0.
96
97      sections_start_lines:
98        Description: 3
99        Return: 6
100
101      parameterdescs:
102        arg1: |
103          @arg1 does nothing
104      parameterlist:
105        - arg1
106      parameterdesc_start_lines:
107        arg1: 2
108      parametertypes:
109        arg1: char *arg1
110
111      other_stuff:
112        func_macro: false
113        functiontype: int
114        purpose: "Exported function"
115        typedef: false
116
117    rst: |
118      .. c:function:: int func2 (char *arg1)
119
120        Exported function
121
122      .. container:: kernelindent
123
124        **Parameters**
125
126        ``char *arg1``
127          **arg1** does nothing
128
129        **Description**
130
131        Does nothing
132
133        **Return**
134
135        always return 0.
136
137    # TODO: how to handle timestamps at .TH?
138    man: |
139      .TH "func2" 9 "February 2026"  "" "Kernel API Manual"
140      .SH NAME
141      func2 \- Exported function
142      .SH SYNOPSIS
143      .B "int" func2
144      .BI "(char *arg1 "  ");"
145      .SH ARGUMENTS
146      .IP "arg1" 12
147      \fIarg1\fP does nothing
148      .SH "DESCRIPTION"
149      Does nothing
150      .SH "RETURN"
151      always return 0.
152      .SH "SEE ALSO"
153      .PP
154      Kernel file \fBfunc2.c\fR
155