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

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

[Michal Wajdeczko]

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(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 2791f8195203..6f91b26d63b6 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -246,7 +246,7 @@ my $decl_type;
 # Name of the kernel-doc identifier for non-DOC markups
 my $identifier;
 
-my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
+my $doc_start = '^[ \t]*/\*\*\s*$'; # Allow whitespace before and at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
 my $doc_com_body = '\s*\* ?';
-- 
2.43.0

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

[Jonathan Corbet]

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?

jon

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

[Michal Wajdeczko]

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

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

[Jonathan Corbet]

Michal Wajdeczko <michal.wajdeczko@intel.com> writes:

> 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

I won't disagree with that.  But we really can't add that many more
warnings to a docs build.  Even though getting rid of all the warnings
seems like a hopeless task, it is still a goal; adding another pile will
cause any other new warnings to be completely buried.

How hard would it to talk you into submitting patches to all of the
relevant maintainers fixing the erroneous comments? :)

Thanks,

jon