[v1] docs/conf.py: add function attribute '__fix_address' to conf.py

[PATCH net-next] docs/conf.py: add function attribute '__fix_address' to conf.py

Posted by menglong8.dong@gmail.com 3 years, 7 months ago

From: Menglong Dong <imagedong@tencent.com>

Stephen Rothwell report that the function attribute '__fix_address'
causes a warning when create html docs with the command:

  make htmldocs

Therefor, add this attribute to c_id_attributes in Documentation/conf.py
to clean this warning.

BTW, I'm not able to reproduce this warning (both ubuntu and centos are
tested). I will appreciate it if anyone can have a test for this
commit.

Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Menglong Dong <imagedong@tencent.com>
---
 Documentation/conf.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 934727e23e0e..255384d094bf 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -86,6 +86,7 @@ if major >= 3:
             "__used",
             "__weak",
             "noinline",
+            "__fix_address",
 
             # include/linux/memblock.h:
             "__init_memblock",
-- 
2.37.2

Re: [PATCH net-next] docs/conf.py: add function attribute '__fix_address' to conf.py

Posted by Bagas Sanjaya 3 years, 7 months ago

On Fri, Aug 26, 2022 at 02:19:14PM +0800, menglong8.dong@gmail.com wrote:
> From: Menglong Dong <imagedong@tencent.com>
> 
> Stephen Rothwell report that the function attribute '__fix_address'
> causes a warning when create html docs with the command:
> 
>   make htmldocs
> 
> Therefor, add this attribute to c_id_attributes in Documentation/conf.py
> to clean this warning.
> 
> BTW, I'm not able to reproduce this warning (both ubuntu and centos are
> tested). I will appreciate it if anyone can have a test for this
> commit.
> 
Hi,

The patch description can be improved, like:
"Stephen Rothwell reported htmldocs warning when merging net-next:

Documentation/networking/kapi:26: net/core/skbuff.c:780: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 19]
  void __fix_address kfree_skb_reason (struct sk_buff *skb, enum skb_drop_reason reason)
  -------------------^

Add __fix_address keyword to c_id_attributes array in conf.py to fix the
warning."

So next time when you spot documentation warnings like above, specify the
exact warning in the patch description. This will help reviewers what warning
the patch is fixing.

> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Signed-off-by: Menglong Dong <imagedong@tencent.com>

Also, don't forget to add Link tag, like:
Link: https://lore.kernel.org/linux-next/20220825154105.534d78ab@canb.auug.org.au/

Otherwise, the warning disappeared on my htmldocs build, thanks.

Tested-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH net-next] docs/conf.py: add function attribute '__fix_address' to conf.py

Posted by Bagas Sanjaya 3 years, 7 months ago

On 8/26/22 16:39, Bagas Sanjaya wrote:
> On Fri, Aug 26, 2022 at 02:19:14PM +0800, menglong8.dong@gmail.com wrote:
>> From: Menglong Dong <imagedong@tencent.com>
>>
>> Stephen Rothwell report that the function attribute '__fix_address'
>> causes a warning when create html docs with the command:
>>
>>   make htmldocs
>>
>> Therefor, add this attribute to c_id_attributes in Documentation/conf.py
>> to clean this warning.
>>
>> BTW, I'm not able to reproduce this warning (both ubuntu and centos are
>> tested). I will appreciate it if anyone can have a test for this
>> commit.
>>
> Hi,
> 
> The patch description can be improved, like:
> "Stephen Rothwell reported htmldocs warning when merging net-next:
> 
> Documentation/networking/kapi:26: net/core/skbuff.c:780: WARNING: Error in declarator or parameters
> Invalid C declaration: Expecting "(" in parameters. [error at 19]
>   void __fix_address kfree_skb_reason (struct sk_buff *skb, enum skb_drop_reason reason)
>   -------------------^
> 
> Add __fix_address keyword to c_id_attributes array in conf.py to fix the
> warning."
> 
> So next time when you spot documentation warnings like above, specify the
> exact warning in the patch description. This will help reviewers what warning
> the patch is fixing.
> 
>> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
>> Signed-off-by: Menglong Dong <imagedong@tencent.com>
> 
> Also, don't forget to add Link tag, like:
> Link: https://lore.kernel.org/linux-next/20220825154105.534d78ab@canb.auug.org.au/
> 
> Otherwise, the warning disappeared on my htmldocs build, thanks.
> 
> Tested-by: Bagas Sanjaya <bagasdotme@gmail.com>
> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
> 

Oops, ignore my Reviewed-by above (not LGTM until my comments above
are addressed).

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH net-next] docs/conf.py: add function attribute '__fix_address' to conf.py

Posted by Menglong Dong 3 years, 7 months ago

On Fri, Aug 26, 2022 at 8:47 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> On 8/26/22 16:39, Bagas Sanjaya wrote:
> > On Fri, Aug 26, 2022 at 02:19:14PM +0800, menglong8.dong@gmail.com wrote:
> >> From: Menglong Dong <imagedong@tencent.com>
> >>
> >> Stephen Rothwell report that the function attribute '__fix_address'
> >> causes a warning when create html docs with the command:
> >>
> >>   make htmldocs
> >>
> >> Therefor, add this attribute to c_id_attributes in Documentation/conf.py
> >> to clean this warning.
> >>
> >> BTW, I'm not able to reproduce this warning (both ubuntu and centos are
> >> tested). I will appreciate it if anyone can have a test for this
> >> commit.
> >>
> > Hi,
> >
> > The patch description can be improved, like:
> > "Stephen Rothwell reported htmldocs warning when merging net-next:
> >
> > Documentation/networking/kapi:26: net/core/skbuff.c:780: WARNING: Error in declarator or parameters
> > Invalid C declaration: Expecting "(" in parameters. [error at 19]
> >   void __fix_address kfree_skb_reason (struct sk_buff *skb, enum skb_drop_reason reason)
> >   -------------------^
> >
> > Add __fix_address keyword to c_id_attributes array in conf.py to fix the
> > warning."
> >
> > So next time when you spot documentation warnings like above, specify the
> > exact warning in the patch description. This will help reviewers what warning
> > the patch is fixing.
> >
> >> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> >> Signed-off-by: Menglong Dong <imagedong@tencent.com>
> >
> > Also, don't forget to add Link tag, like:
> > Link: https://lore.kernel.org/linux-next/20220825154105.534d78ab@canb.auug.org.au/
> >
> > Otherwise, the warning disappeared on my htmldocs build, thanks.
> >
> > Tested-by: Bagas Sanjaya <bagasdotme@gmail.com>
> > Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
> >
>
> Oops, ignore my Reviewed-by above (not LGTM until my comments above
> are addressed).

Thanks for your advice and the testing. I'll send a V2 with your
comments addressed, and with your Reviewed-by and Tested-by
tags.

Menglong Dong

>
> --
> An old man doll... just what I always wanted! - Clara