linux-next: build warning for a long time

linux-next: build warning for a long time

[Stephen Rothwell]

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

Hi all,

From before the git era, an htmldocs build (if we had such a thing back
then) would complain like this:

Documentation/driver-api/usb/usb:164: drivers/usb/core/message.c:968: WARNING: Duplicate C declaration, also defined at driver-api/usb/gadget:804.
Declaration is '.. c:function:: int usb_string (struct usb_device *dev, int index, char *buf, size_t size)'.

I assume it is confused because we have documented both a function and a
data type called "usb_string".  The former in drivers/usb/core/message.c
and the latter in include/linux/usb/gadget.h.

There are about 46 references to the function and 105 to the struct.
We could rename the function to usb_string_utf8 ...
-- 
Cheers,
Stephen Rothwell

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

Re: linux-next: build warning for a long time

[Greg KH]

On Fri, Oct 11, 2024 at 05:24:42PM +1100, Stephen Rothwell wrote:
> Hi all,
> 
> From before the git era, an htmldocs build (if we had such a thing back
> then) would complain like this:
> 
> Documentation/driver-api/usb/usb:164: drivers/usb/core/message.c:968: WARNING: Duplicate C declaration, also defined at driver-api/usb/gadget:804.
> Declaration is '.. c:function:: int usb_string (struct usb_device *dev, int index, char *buf, size_t size)'.
> 
> I assume it is confused because we have documented both a function and a
> data type called "usb_string".  The former in drivers/usb/core/message.c
> and the latter in include/linux/usb/gadget.h.
> 
> There are about 46 references to the function and 105 to the struct.
> We could rename the function to usb_string_utf8 ...

But usb strings are not in utf8 format :)

As C can handle this just fine, odds are sphinx should also be able to
handle this?

thanks,

greg k-h

Re: linux-next: build warning for a long time

[Akira Yokosawa]

> On Fri, Oct 11, 2024 at 05:24:42PM +1100, Stephen Rothwell wrote:
>> Hi all,
>> 
>> From before the git era, an htmldocs build (if we had such a thing back
>> then) would complain like this:
>> 
>> Documentation/driver-api/usb/usb:164: drivers/usb/core/message.c:968: WARNING: Duplicate C declaration, also defined at driver-api/usb/gadget:804.
>> Declaration is '.. c:function:: int usb_string (struct usb_device *dev, int index, char *buf, size_t size)'.
>> 
>> I assume it is confused because we have documented both a function and a
>> data type called "usb_string".  The former in drivers/usb/core/message.c
>> and the latter in include/linux/usb/gadget.h.
>> 
>> There are about 46 references to the function and 105 to the struct.
>> We could rename the function to usb_string_utf8 ...
> 
> But usb strings are not in utf8 format :)
> 
> As C can handle this just fine, odds are sphinx should also be able to
> handle this?
> 
> thanks,
> 
> greg k-h

Re: linux-next: build warning for a long time

[Akira Yokosawa]

Hi,

Sorry for the premature reply I just sent...

On Fri, 11 Oct 2024 08:31:47 +0200, Greg KH wrote:
> On Fri, Oct 11, 2024 at 05:24:42PM +1100, Stephen Rothwell wrote:
>> Hi all,
>> 
>> From before the git era, an htmldocs build (if we had such a thing back
>> then) would complain like this:
>> 
>> Documentation/driver-api/usb/usb:164: drivers/usb/core/message.c:968: WARNING: Duplicate C declaration, also defined at driver-api/usb/gadget:804.
>> Declaration is '.. c:function:: int usb_string (struct usb_device *dev, int index, char *buf, size_t size)'.
>> 
>> I assume it is confused because we have documented both a function and a
>> data type called "usb_string".  The former in drivers/usb/core/message.c
>> and the latter in include/linux/usb/gadget.h.
>> 
>> There are about 46 references to the function and 105 to the struct.
>> We could rename the function to usb_string_utf8 ...
> 
> But usb strings are not in utf8 format :)
> 
> As C can handle this just fine, odds are sphinx should also be able to
> handle this?
> 
> thanks,

This is a well known issue of Sphinx, which is taking a looong time to be
properly fixed.

For your info, this is a short summary I posted last March:

  https://lore.kernel.org/f735ce0b-db1e-49bc-86ac-b5ab8e4aec31@gmail.com/

I think we need to wait patiently for a fix(es) of Sphinx.

HTH,

Akira