[PATCH docs] scripts: kernel-doc: support private / public marking for enums

[PATCH docs] scripts: kernel-doc: support private / public marking for enums

[Jakub Kicinski]

Enums benefit from private markings, too. For netlink attribute
name enums always end with a pair of __$n_MAX and $n_MAX members.
Documenting them feels a bit tedious.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
Hi Jon, we've CCed you recently on a related discussion
but it appears that the fix is simple enough so posting
it before you had a chance to reply.
---
 scripts/kernel-doc | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 2486689ffc7b..66b554897899 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1301,6 +1301,9 @@ sub dump_enum($$) {
     my $file = shift;
     my $members;
 
+    # ignore members marked private:
+    $x =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
+    $x =~ s/\/\*\s*private:.*}/}/gosi;
 
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
     # strip #define macros inside enums
-- 
2.40.1

Re: [PATCH docs] scripts: kernel-doc: support private / public marking for enums

[Randy Dunlap]

On 6/21/23 15:35, Jakub Kicinski wrote:
> Enums benefit from private markings, too. For netlink attribute
> name enums always end with a pair of __$n_MAX and $n_MAX members.
> Documenting them feels a bit tedious.
> 
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
> Hi Jon, we've CCed you recently on a related discussion
> but it appears that the fix is simple enough so posting
> it before you had a chance to reply.
> ---
>  scripts/kernel-doc | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 2486689ffc7b..66b554897899 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1301,6 +1301,9 @@ sub dump_enum($$) {
>      my $file = shift;
>      my $members;
>  
> +    # ignore members marked private:
> +    $x =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
> +    $x =~ s/\/\*\s*private:.*}/}/gosi;
>  
>      $x =~ s@/\*.*?\*/@@gos;	# strip comments.
>      # strip #define macros inside enums

-- 
~Randy

Re: [PATCH docs] scripts: kernel-doc: support private / public marking for enums

[Randy Dunlap]

Hi Jon,

On 6/21/23 20:10, Randy Dunlap wrote:
> 
> 
> On 6/21/23 15:35, Jakub Kicinski wrote:
>> Enums benefit from private markings, too. For netlink attribute
>> name enums always end with a pair of __$n_MAX and $n_MAX members.
>> Documenting them feels a bit tedious.
>>
>> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
> 
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>
> 
> Thanks.

I have a need for this patch. Are you planning to merge it?

in current linux-next docs build:

../include/drm/drm_connector.h:527: warning: Enum value 'DRM_MODE_COLORIMETRY_COUNT' not described in enum 'drm_colorspace'

That enum identifier could/should be marked as private:.

Thanks.

> 
>> ---
>> Hi Jon, we've CCed you recently on a related discussion
>> but it appears that the fix is simple enough so posting
>> it before you had a chance to reply.
>> ---
>>  scripts/kernel-doc | 3 +++
>>  1 file changed, 3 insertions(+)
>>
>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
>> index 2486689ffc7b..66b554897899 100755
>> --- a/scripts/kernel-doc
>> +++ b/scripts/kernel-doc
>> @@ -1301,6 +1301,9 @@ sub dump_enum($$) {
>>      my $file = shift;
>>      my $members;
>>  
>> +    # ignore members marked private:
>> +    $x =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
>> +    $x =~ s/\/\*\s*private:.*}/}/gosi;
>>  
>>      $x =~ s@/\*.*?\*/@@gos;	# strip comments.
>>      # strip #define macros inside enums
> 

-- 
~Randy

Re: [PATCH docs] scripts: kernel-doc: support private / public marking for enums

[Jonathan Corbet]

Randy Dunlap <rdunlap@infradead.org> writes:

> Hi Jon,
>
> On 6/21/23 20:10, Randy Dunlap wrote:
>> 
>> 
>> On 6/21/23 15:35, Jakub Kicinski wrote:
>>> Enums benefit from private markings, too. For netlink attribute
>>> name enums always end with a pair of __$n_MAX and $n_MAX members.
>>> Documenting them feels a bit tedious.
>>>
>>> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
>> 
>> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
>> Tested-by: Randy Dunlap <rdunlap@infradead.org>
>> 
>> Thanks.
>
> I have a need for this patch. Are you planning to merge it?

It's commit e27cb89a22ad in 6.5-rc1 ...

Thanks,

jon

Re: [PATCH docs] scripts: kernel-doc: support private / public marking for enums

[Randy Dunlap]

On 7/14/23 06:29, Jonathan Corbet wrote:
> Randy Dunlap <rdunlap@infradead.org> writes:
> 
>> Hi Jon,
>>
>> On 6/21/23 20:10, Randy Dunlap wrote:
>>>
>>>
>>> On 6/21/23 15:35, Jakub Kicinski wrote:
>>>> Enums benefit from private markings, too. For netlink attribute
>>>> name enums always end with a pair of __$n_MAX and $n_MAX members.
>>>> Documenting them feels a bit tedious.
>>>>
>>>> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
>>>
>>> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
>>> Tested-by: Randy Dunlap <rdunlap@infradead.org>
>>>
>>> Thanks.
>>
>> I have a need for this patch. Are you planning to merge it?
> 
> It's commit e27cb89a22ad in 6.5-rc1 ...

Oops, my bad, sorry about that.

I'm testing with linux-next. Something is rotten here /methinks.

I will check it out.

-- 
~Randy

Re: [PATCH docs] scripts: kernel-doc: support private / public marking for enums

[Randy Dunlap]

On 7/14/23 08:15, Randy Dunlap wrote:
> 
> 
> On 7/14/23 06:29, Jonathan Corbet wrote:
>> Randy Dunlap <rdunlap@infradead.org> writes:
>>
>>> Hi Jon,
>>>
>>> On 6/21/23 20:10, Randy Dunlap wrote:
>>>>
>>>>
>>>> On 6/21/23 15:35, Jakub Kicinski wrote:
>>>>> Enums benefit from private markings, too. For netlink attribute
>>>>> name enums always end with a pair of __$n_MAX and $n_MAX members.
>>>>> Documenting them feels a bit tedious.
>>>>>
>>>>> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
>>>>
>>>> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
>>>> Tested-by: Randy Dunlap <rdunlap@infradead.org>
>>>>
>>>> Thanks.
>>>
>>> I have a need for this patch. Are you planning to merge it?
>>
>> It's commit e27cb89a22ad in 6.5-rc1 ...
> 
> Oops, my bad, sorry about that.
> 
> I'm testing with linux-next. Something is rotten here /methinks.
> 
> I will check it out.

Apparently this was due to user error -- it works today.
Sorry about the noise.

Re: [PATCH docs] scripts: kernel-doc: support private / public marking for enums

[Jonathan Corbet]

Jakub Kicinski <kuba@kernel.org> writes:

> Enums benefit from private markings, too. For netlink attribute
> name enums always end with a pair of __$n_MAX and $n_MAX members.
> Documenting them feels a bit tedious.
>
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
> ---
> Hi Jon, we've CCed you recently on a related discussion
> but it appears that the fix is simple enough so posting
> it before you had a chance to reply.
> ---
>  scripts/kernel-doc | 3 +++
>  1 file changed, 3 insertions(+)

Hmm...somehow I missed the discussion, sorry.  Fix applied, thanks.

jon