linux-next: build warning after merge of the hmm tree

linux-next: build warning after merge of the hmm tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 482 bytes --]

Hi all,

After merging the hmm tree, today's linux-next build (htmldocs) produced
this warning:

include/cxl/features.h:66: warning: Excess struct member 'num_features' description in 'cxl_features_state'
include/cxl/features.h:66: warning: Excess struct member 'ent' description in 'cxl_features_state'

Maybe introduced by commit

  a53a6004e7a5 ("cxl: Add FWCTL support to CXL")

Maybe the indentation in the comments is confusing?

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

linux-next: build warning after merge of the hmm tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 286 bytes --]

Hi all,

After merging the hmm tree, today's linux-next build (htmldocs) produced
this warning:

include/uapi/fwctl/pds.h:1: warning: no structured comments found

Introduced by commit

  16384467ec8f ("pds_fwctl: add Documentation entries")

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: build warning after merge of the hmm tree

[Jason Gunthorpe]

On Tue, Mar 18, 2025 at 09:39:06PM +1100, Stephen Rothwell wrote:
> Hi all,
> 
> After merging the hmm tree, today's linux-next build (htmldocs) produced
> this warning:
> 
> include/uapi/fwctl/pds.h:1: warning: no structured comments found
> 
> Introduced by commit
> 
>   16384467ec8f ("pds_fwctl: add Documentation entries")

Thanks Stephen,

Shannon, this is the same issue CXL had, do not include C header files
from the RST side if they do not have any kdoc comments.

Documentation/userspace-api/fwctl/fwctl.rst:.. kernel-doc:: include/uapi/fwctl/pds.h
Documentation/userspace-api/fwctl/pds_fwctl.rst:.. kernel-doc:: include/uapi/fwctl/pds.h

It looks like in this case you should probably add kdoc comments to
pds.h

Jason

Re: linux-next: build warning after merge of the hmm tree

[Nelson, Shannon]

On 3/18/2025 4:09 AM, Jason Gunthorpe wrote:
> 
> On Tue, Mar 18, 2025 at 09:39:06PM +1100, Stephen Rothwell wrote:
>> Hi all,
>>
>> After merging the hmm tree, today's linux-next build (htmldocs) produced
>> this warning:
>>
>> include/uapi/fwctl/pds.h:1: warning: no structured comments found
>>
>> Introduced by commit
>>
>>    16384467ec8f ("pds_fwctl: add Documentation entries")
> 
> Thanks Stephen,
> 
> Shannon, this is the same issue CXL had, do not include C header files
> from the RST side if they do not have any kdoc comments.
> 
> Documentation/userspace-api/fwctl/fwctl.rst:.. kernel-doc:: include/uapi/fwctl/pds.h
> Documentation/userspace-api/fwctl/pds_fwctl.rst:.. kernel-doc:: include/uapi/fwctl/pds.h
> 
> It looks like in this case you should probably add kdoc comments to
> pds.h
> 
> Jason

Funny, I was just doing that last evening.
Thanks, I'll be updating my patchset soon.

sln

linux-next: build warning after merge of the hmm tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 369 bytes --]

Hi all,

After merging the hmm tree, today's linux-next build (htmldocs) produced
this warning:

include/uapi/fwctl/cxl.h:53: warning: Function parameter or struct member 'payload' not described in 'fwctl_rpc_cxl_out'

Introduced by commit

  72749296d686 ("cxl: Add support to handle user feature commands for get feature")

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

linux-next: build warning after merge of the hmm tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 292 bytes --]

Hi all,

After merging the hmm tree, today's linux-next build (htmldocs) produced
this warning:

Error: Cannot open file /home/sfr/next/next/drivers/cxl/features.c

Introduced by commit

  da0dd17604d4 ("fwctl/cxl: Add documentation to FWCTL CXL")

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: build warning after merge of the hmm tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 474 bytes --]

Hi all,

On Fri, 7 Mar 2025 19:57:15 +1100 Stephen Rothwell <sfr@canb.auug.org.au> wrote:
>
> After merging the hmm tree, today's linux-next build (htmldocs) produced
> this warning:
> 
> Error: Cannot open file /home/sfr/next/next/drivers/cxl/features.c
> 
> Introduced by commit
> 
>   da0dd17604d4 ("fwctl/cxl: Add documentation to FWCTL CXL")

Also:

include/uapi/cxl/features.h:1: warning: no structured comments found

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: build warning after merge of the hmm tree

[Jason Gunthorpe]

On Fri, Mar 07, 2025 at 07:57:15PM +1100, Stephen Rothwell wrote:
> Hi all,
> 
> After merging the hmm tree, today's linux-next build (htmldocs) produced
> this warning:
> 
> Error: Cannot open file /home/sfr/next/next/drivers/cxl/features.c
> 
> Introduced by commit
> 
>   da0dd17604d4 ("fwctl/cxl: Add documentation to FWCTL CXL")

Thanks Stephen,

Dave can you fix all of thes kdoc bugs and post a new version?

Jason

Re: linux-next: build warning after merge of the hmm tree

[Dave Jiang]

On 3/7/25 8:04 AM, Jason Gunthorpe wrote:
> On Fri, Mar 07, 2025 at 07:57:15PM +1100, Stephen Rothwell wrote:
>> Hi all,
>>
>> After merging the hmm tree, today's linux-next build (htmldocs) produced
>> this warning:
>>
>> Error: Cannot open file /home/sfr/next/next/drivers/cxl/features.c
>>
>> Introduced by commit
>>
>>   da0dd17604d4 ("fwctl/cxl: Add documentation to FWCTL CXL")
> 
> Thanks Stephen,
> 
> Dave can you fix all of thes kdoc bugs and post a new version?
>

After fixing up most of the issues, I cannot figure out what the issue is for this one:
./include/uapi/cxl/features.h:1: warning: no structured comments found

I'm not seeing any issues in the header via visual inspection. Running kernel_docs against the file yields no warning or error either. Deleting all the contents from that header file and I'm still seeing the warning. Makes no sense.... 

I'll repost the series on the mailing list with what I have fixed.

 
> Jason

Re: linux-next: build warning after merge of the hmm tree

[Jason Gunthorpe]

> After fixing up most of the issues, I cannot figure out what the issue is for this one:
> ./include/uapi/cxl/features.h:1: warning: no structured comments found

It is because of this:

Documentation/userspace-api/fwctl/fwctl-cxl.rst:.. kernel-doc:: include/uapi/cxl/features.h

Which includes the file and as the message says there are not kdoc
comments in the file.

I'll squish this into your v8:

--- a/Documentation/userspace-api/fwctl/fwctl-cxl.rst
+++ b/Documentation/userspace-api/fwctl/fwctl-cxl.rst
@@ -39,7 +39,6 @@ fwctl cxl User API
 ==================
 
 .. kernel-doc:: include/uapi/fwctl/cxl.h
-.. kernel-doc:: include/uapi/cxl/features.h
 
 1. Driver info query
 --------------------

Jason