On 05.09.2024 21:56, Jonathan Corbet wrote:
> Michal Wajdeczko <michal.wajdeczko@xxxxxxxxx> writes:
>
>> There is some existing documentation that is formatted with some
>> indent at the beginning (like one in include/kunit/visibility.h).
>>
>> However, such notation is not recognized by the script and attempt
>> to include that in kernel documentation fails with:
>>
>> ../include/kunit/visibility.h:1: warning: no structured comments found
>>
>> Change the doc_start regex to also match /** with some whitespaces
>> at beginning of the line.
>>
>> Signed-off-by: Michal Wajdeczko <michal.wajdeczko@xxxxxxxxx>
>> ---
>> Cc: Jonathan Corbet <corbet@xxxxxxx>
>> Cc: Rae Moar <rmoar@xxxxxxxxxx>
>> ---
>> scripts/kernel-doc | 2 +-
>> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> This patch adds vast numbers of build errors and warnings; did you try a
> build with it?
Oops, I'm pretty sure that I tried, but likely didn't rerun on fresh
tree, so seen just changes resulted from adding visibility.h
Sorry about that.
But looking now at those new errors/warnings and IMO it seems that all
of them are valid, mostly due to mistakes with formatting of the
comments, not that tool is now broken.
Few examples:
../kernel/resource.c:148: warning: This comment starts with '/**', but
isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* If the resource was allocated using memblock early during
145 static void free_resource(struct resource *res)
146 {
147 /**
148 * If the resource was allocated using memblock early
this should be formatted as normal multi-line comment inside the
function, not in a kernel-doc fashion
../include/drm/drm_atomic.h:170: warning: Cannot understand *
@commit:
on line 170 - I thought it was a doc line
165 struct __drm_crtcs_state {
166 struct drm_crtc *ptr;
167 struct drm_crtc_state *state, *old_state, *new_state;
168
169 /**
170 * @commit:
171 *
172 * A reference to the CRTC commit object that is kept
missing kernel-doc comment for the top level struct, only selected
members have kernel-doc
