Re: [PATCH] kernel-doc: Allow whitespace before comment start

[Michal Wajdeczko <michal.wajdeczko@intel.com>]

On 05.09.2024 21:56, Jonathan Corbet wrote:
> Michal Wajdeczko <michal.wajdeczko@intel.com> 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@intel.com>
>> ---
>> Cc: Jonathan Corbet <corbet@lwn.net>
>> Cc: Rae Moar <rmoar@google.com>
>> ---
>>  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