Skip to contentSkip to conversation

scripts: kernel-doc: support private / public marking for enums

PATCH In review Jakub Kicinski 3 participants 7 messages Jun 21, 2023 – Jul 16, 2023

Subsystems (3)
lore
Share & tools
lore

Jakub Kicinski

author maintainer
#0 lore raw

PATCH 1/1 scripts: kernel-doc: support private / public marking for enums

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.

---
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(+)
scripts/kernel-doc +3 -0
index 2486689ffc7b..66b554897899 100755
@@ -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
Signature · 1 line
2.40.1
reviewer Reviewed-by Tested-by on v1 1/1
#1 lore raw
Quoted 5 lines · 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.

Thanks.

Quoted 22 lines

---
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(+)
scripts/kernel-doc +3 -0
index 2486689ffc7b..66b554897899 100755
@@ -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
Signature · 1 line
~Randy
maintainer
#6 lore raw
In reply to Jakub Kicinski
Quoted 4 lines · 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.

Quoted 8 lines

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

reviewer
#2 lore raw
In reply to Randy Dunlap

Hi Jon,

Quoted 7 lines · Randy Dunlap
Quoted 4 lines · 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.

Quoted 6 lines
Quoted 1 line

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.

Quoted 24 lines
Quoted 23 lines

---
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(+)
scripts/kernel-doc +3 -0
index 2486689ffc7b..66b554897899 100755
@@ -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
Signature · 1 line
~Randy
maintainer
#3 lore raw
Quoted 10 lines · Randy Dunlap

Hi Jon,

Quoted 7 lines · Randy Dunlap
Quoted 4 lines · 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.

Quoted 8 lines
Quoted 6 lines
Quoted 1 line

Thanks.

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

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

Thanks,

jon

reviewer
#4 lore raw
Quoted 14 lines · Jonathan Corbet
Quoted 12 lines · Randy Dunlap

Hi Jon,

Quoted 9 lines · Randy Dunlap
Quoted 5 lines · 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.

Quoted 8 lines
Quoted 6 lines
Quoted 4 lines

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.

Signature · 1 line
~Randy
reviewer
#5 lore raw
Quoted 24 lines · Randy Dunlap
Quoted 21 lines · Jonathan Corbet
Quoted 18 lines · Randy Dunlap

Hi Jon,

Quoted 7 lines · Randy Dunlap
Quoted 4 lines · 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.

Quoted 6 lines
Quoted 1 line

Thanks.

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

Quoted 7 lines
Quoted 1 line

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.