Re: [PATCH 3/8] docs: kdoc: don't add broken comments inside prototypes

Re: [PATCH 3/8] docs: kdoc: don't add broken comments inside prototypes

[kernel test robot]

:::::: 
:::::: Manual check reason: "only suspicious fbc files changed"
:::::: 

BCC: lkp@intel.com
CC: oe-kbuild-all@lists.linux.dev
In-Reply-To: <18e577dbbd538dcc22945ff139fe3638344e14f0.1773074166.git.mchehab+huawei@kernel.org>
References: <18e577dbbd538dcc22945ff139fe3638344e14f0.1773074166.git.mchehab+huawei@kernel.org>
TO: Mauro Carvalho Chehab <mchehab@kernel.org>
CC: linux-media@vger.kernel.org
TO: Jonathan Corbet <corbet@lwn.net>
TO: Linux Doc Mailing List <linux-doc@vger.kernel.org>
CC: Mauro Carvalho Chehab <mchehab@kernel.org>
CC: linux-media@vger.kernel.org
CC: linux-kernel@vger.kernel.org
CC: Aleksandr Loktionov <aleksandr.loktionov@intel.com>
CC: Randy Dunlap <rdunlap@infradead.org>

Hi Mauro,

kernel test robot noticed the following build warnings:

[auto build test WARNING on lwn/docs-next]
[also build test WARNING on linus/master v7.0-rc3 next-20260309]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Mauro-Carvalho-Chehab/docs-python-add-helpers-to-run-unit-tests/20260310-005923
base:   git://git.lwn.net/linux.git docs-next
patch link:    https://lore.kernel.org/r/18e577dbbd538dcc22945ff139fe3638344e14f0.1773074166.git.mchehab%2Bhuawei%40kernel.org
patch subject: [PATCH 3/8] docs: kdoc: don't add broken comments inside prototypes
:::::: branch date: 15 hours ago
:::::: commit date: 15 hours ago
config: powerpc64-randconfig-001-20260310 (https://download.01.org/0day-ci/archive/20260310/202603101636.5yiLB85l-lkp@intel.com/config)
compiler: powerpc64-linux-gcc (GCC) 15.2.0
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20260310/202603101636.5yiLB85l-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/r/202603101636.5yiLB85l-lkp@intel.com/

All warnings (new ones prefixed by >>):

   Warning: drivers/ps3/ps3-sys-manager.c:35 Incorrect use of kernel-doc format:  * struct ps3_sys_manager_header - System manager message header.
>> Warning: drivers/ps3/ps3-sys-manager.c:43 cannot understand function prototype: '/**
    * struct ps3_sys_manager_header - System manager message header.  * @version: Header version, currently 1.  * @size: Header size in bytes, currently 16.  * @payload_size: Message payload size in bytes.  * @service_id: Message type, one of enum ps3_sys_manager_service_id.  * @request_tag: Unique number to identify reply.  */  struct ps3_sys_manager_header'
   Warning: drivers/ps3/ps3-sys-manager.c:66 Cannot find identifier on line:
    * @PS3_SM_RX_MSG_LEN_MIN - Shortest received message length.
   Warning: drivers/ps3/ps3-sys-manager.c:67 Cannot find identifier on line:
    * @PS3_SM_RX_MSG_LEN_MAX - Longest received message length.
   Warning: drivers/ps3/ps3-sys-manager.c:68 Cannot find identifier on line:
    *
   Warning: drivers/ps3/ps3-sys-manager.c:69 This comment starts with '/**', but isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst
    * Currently all messages received from the system manager are either
   Warning: drivers/ps3/ps3-sys-manager.c:171 Enum value 'PS3_SM_NEXT_OP_SYS_SHUTDOWN' not described in enum 'ps3_sys_manager_next_op'
   Warning: drivers/ps3/ps3-sys-manager.c:171 Enum value 'PS3_SM_NEXT_OP_SYS_REBOOT' not described in enum 'ps3_sys_manager_next_op'
   Warning: drivers/ps3/ps3-sys-manager.c:171 Enum value 'PS3_SM_NEXT_OP_LPAR_REBOOT' not described in enum 'ps3_sys_manager_next_op'
   Warning: drivers/ps3/ps3-sys-manager.c:198 cannot understand function prototype: 'u32 user_wake_sources = PS3_SM_WAKE_DEFAULT;'
   Warning: drivers/ps3/ps3-sys-manager.c:212 Enum value 'PS3_SM_CMD_SHUTDOWN' not described in enum 'ps3_sys_manager_cmd'
   Warning: drivers/ps3/ps3-sys-manager.c:222 cannot understand function prototype: 'unsigned int ps3_sm_force_power_off;'
   Warning: drivers/ps3/ps3-sys-manager.c:231 function parameter 'dev' not described in 'ps3_sys_manager_write'
   Warning: drivers/ps3/ps3-sys-manager.c:231 function parameter 'header' not described in 'ps3_sys_manager_write'
   Warning: drivers/ps3/ps3-sys-manager.c:231 function parameter 'payload' not described in 'ps3_sys_manager_write'
   Warning: drivers/ps3/ps3-sys-manager.c:255 function parameter 'dev' not described in 'ps3_sys_manager_send_attr'
   Warning: drivers/ps3/ps3-sys-manager.c:255 function parameter 'attr' not described in 'ps3_sys_manager_send_attr'
   Warning: drivers/ps3/ps3-sys-manager.c:289 function parameter 'dev' not described in 'ps3_sys_manager_send_next_op'
   Warning: drivers/ps3/ps3-sys-manager.c:289 function parameter 'op' not described in 'ps3_sys_manager_send_next_op'
   Warning: drivers/ps3/ps3-sys-manager.c:289 function parameter 'wake_source' not described in 'ps3_sys_manager_send_next_op'
   Warning: drivers/ps3/ps3-sys-manager.c:333 function parameter 'dev' not described in 'ps3_sys_manager_send_request_shutdown'
   Warning: drivers/ps3/ps3-sys-manager.c:370 function parameter 'dev' not described in 'ps3_sys_manager_send_response'
   Warning: drivers/ps3/ps3-sys-manager.c:403 function parameter 'dev' not described in 'ps3_sys_manager_handle_event'
   Warning: drivers/ps3/ps3-sys-manager.c:485 function parameter 'dev' not described in 'ps3_sys_manager_handle_cmd'
   Warning: drivers/ps3/ps3-sys-manager.c:526 function parameter 'dev' not described in 'ps3_sys_manager_handle_msg'
   Warning: drivers/ps3/ps3-sys-manager.c:607 function parameter 'dev' not described in 'ps3_sys_manager_final_power_off'
   Warning: drivers/ps3/ps3-sys-manager.c:631 function parameter 'dev' not described in 'ps3_sys_manager_final_restart'
   Warning: drivers/ps3/ps3-sys-manager.c:670 function parameter 'state' not described in 'ps3_sys_manager_set_wol'
   Warning: drivers/ps3/ps3-sys-manager.c:692 function parameter 'dev' not described in 'ps3_sys_manager_work'
   Warning: drivers/ps3/ps3-sys-manager.c:171 Enum value 'PS3_SM_NEXT_OP_SYS_SHUTDOWN' not described in enum 'ps3_sys_manager_next_op'
   Warning: drivers/ps3/ps3-sys-manager.c:171 Enum value 'PS3_SM_NEXT_OP_SYS_REBOOT' not described in enum 'ps3_sys_manager_next_op'
   Warning: drivers/ps3/ps3-sys-manager.c:171 Enum value 'PS3_SM_NEXT_OP_LPAR_REBOOT' not described in enum 'ps3_sys_manager_next_op'
   Warning: drivers/ps3/ps3-sys-manager.c:212 Enum value 'PS3_SM_CMD_SHUTDOWN' not described in enum 'ps3_sys_manager_cmd'
   Warning: drivers/ps3/ps3-sys-manager.c:231 function parameter 'dev' not described in 'ps3_sys_manager_write'
   Warning: drivers/ps3/ps3-sys-manager.c:231 function parameter 'header' not described in 'ps3_sys_manager_write'
   Warning: drivers/ps3/ps3-sys-manager.c:231 function parameter 'payload' not described in 'ps3_sys_manager_write'
   Warning: drivers/ps3/ps3-sys-manager.c:255 function parameter 'dev' not described in 'ps3_sys_manager_send_attr'
   Warning: drivers/ps3/ps3-sys-manager.c:255 function parameter 'attr' not described in 'ps3_sys_manager_send_attr'
   Warning: drivers/ps3/ps3-sys-manager.c:289 function parameter 'dev' not described in 'ps3_sys_manager_send_next_op'
   Warning: drivers/ps3/ps3-sys-manager.c:289 function parameter 'op' not described in 'ps3_sys_manager_send_next_op'
   Warning: drivers/ps3/ps3-sys-manager.c:289 function parameter 'wake_source' not described in 'ps3_sys_manager_send_next_op'
   Warning: drivers/ps3/ps3-sys-manager.c:333 function parameter 'dev' not described in 'ps3_sys_manager_send_request_shutdown'
   Warning: drivers/ps3/ps3-sys-manager.c:370 function parameter 'dev' not described in 'ps3_sys_manager_send_response'
   Warning: drivers/ps3/ps3-sys-manager.c:403 function parameter 'dev' not described in 'ps3_sys_manager_handle_event'
   Warning: drivers/ps3/ps3-sys-manager.c:485 function parameter 'dev' not described in 'ps3_sys_manager_handle_cmd'
   Warning: drivers/ps3/ps3-sys-manager.c:526 function parameter 'dev' not described in 'ps3_sys_manager_handle_msg'
   Warning: drivers/ps3/ps3-sys-manager.c:607 function parameter 'dev' not described in 'ps3_sys_manager_final_power_off'
   Warning: drivers/ps3/ps3-sys-manager.c:631 function parameter 'dev' not described in 'ps3_sys_manager_final_restart'
   Warning: drivers/ps3/ps3-sys-manager.c:670 function parameter 'state' not described in 'ps3_sys_manager_set_wol'
   Warning: drivers/ps3/ps3-sys-manager.c:692 function parameter 'dev' not described in 'ps3_sys_manager_work'

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

[PATCH 0/8] Fix public/private kernel-doc issues

[Mauro Carvalho Chehab]

Hi Jon,

This patch set fixes public/private handling inside comments.

The current logic has currently an issue: it breaks nested
structs if private: is not followed by public:.

It also solves a currently undefined behavior: now,
public/private are applied only to the current and
inner statements. So, if one does:

  struct {
	struct {
		/* private: */
		int a;
		struct {
			int b;
		};
	};
	int c;
  };

The output will be:

  struct {
	int c;
  };

Besides making sensing itself, the new behavior solves
an issue when struct_group() macros are used, as the
private from one struct_group won't propagate to other
ones nor to the struct encapsulating one or more
struct_group().

This series start with 2 unittests to detect the problem.
If you apply those two patches and run the unit test,
you'll be able to see the issue.

After applying the changes, it renames the unit test,
making it test directly the code there, instead of the
current wrapper at kdoc_re, and add more tests meant
to check the tokenizer itself.

-

As commented previously, I'm now working on a patchset
using the tokenizer for NestedMatch. I have already
some code here, but not properly tested yet.

Anyway, the idea is to keep submitting it in small
chunks, to make it easier to review.

Mauro Carvalho Chehab (8):
  docs: python: add helpers to run unit tests
  unittests: add a testbench to check public/private kdoc comments
  docs: kdoc: don't add broken comments inside prototypes
  docs: kdoc: properly handle empty enum arguments
  docs: kdoc_re: add a C tokenizer
  docs: kdoc: use tokenizer to handle comments on structs
  unittests: test_private: modify it to use CTokenizer directly
  unittests: test_tokenizer: check if the tokenizer works

 Documentation/tools/python.rst       |   2 +
 Documentation/tools/unittest.rst     |  24 ++
 tools/lib/python/kdoc/kdoc_parser.py |  25 +-
 tools/lib/python/kdoc/kdoc_re.py     | 234 ++++++++++++++
 tools/lib/python/unittest_helper.py  | 353 ++++++++++++++++++++
 tools/unittests/test_tokenizer.py    | 462 +++++++++++++++++++++++++++
 6 files changed, 1088 insertions(+), 12 deletions(-)
 create mode 100644 Documentation/tools/unittest.rst
 create mode 100755 tools/lib/python/unittest_helper.py
 create mode 100755 tools/unittests/test_tokenizer.py

-- 
2.52.0

[PATCH 3/8] docs: kdoc: don't add broken comments inside prototypes

[Mauro Carvalho Chehab]

Parsing a file like drivers/scsi/isci/host.h, which contains
broken kernel-doc markups makes it create a prototype that contains
unmatched end comments.

That causes, for instance, struct sci_power_control to be shown this
this prototype:

    struct sci_power_control {
        * it is not. */ bool timer_started;
        */ struct sci_timer timer;
        * requesters field. */ u8 phys_waiting;
        */ u8 phys_granted_power;
        * mapped into requesters via struct sci_phy.phy_index */ struct isci_phy *requesters[SCI_MAX_PHYS];
    };

as comments won't start with "/*" anymore.

Fix the logic to detect such cases, and keep adding the comments
inside it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/lib/python/kdoc/kdoc_parser.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index edf70ba139a5..086579d00b5c 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -1355,6 +1355,12 @@ class KernelDoc:
         elif doc_content.search(line):
             self.emit_msg(ln, f"Incorrect use of kernel-doc format: {line}")
             self.state = state.PROTO
+
+            #
+            # Don't let it add partial comments at the code, as breaks the
+            # logic meant to remove comments from prototypes.
+            #
+            self.process_proto_type(ln, "/**\n" + line)
         # else ... ??
 
     def process_inline_text(self, ln, line):
-- 
2.52.0