Sphinx error fixed for inline literal end-string in include/linux/workqueue.h

Fixed Error in Workqueue Documentation in the kernel-doc comment for alloc_workqueue function in include/linux/workqueue.h, the error was "Inline literal start-string without end-string" which was fixed by removing the inline literal.
Kernel Version - 6.9.0-rc5

---
 include/linux/workqueue.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 158784dd189a..b4aebd981a23 100644
@@ -490,7 +490,7 @@ void workqueue_softirq_dead(unsigned int cpu);
  * min_active which is set to min(@max_active, %WQ_DFL_MIN_ACTIVE). This means
  * that the sum of per-node max_active's may be larger than @max_active.
  *
- * For detailed information on %WQ_* flags, please refer to
+ * For detailed information on WQ_* flags, please refer to
  * Documentation/core-api/workqueue.rst.
  *
  * RETURNS:

2.34.1

Hello,

There was a slightly different patch submission on the same issue the other day. You might be interested in seeing my response to it [1].

[1]: https://lore.kernel.org/r/[email protected]/

Quoting below for your convenience:

Unfortunately, there's been no patch submission in this direction so far. I'd be delighted if you can try this approach instead.

Thanks, Akira

The kernel-doc script uses the $type_constant2 variable to match expressions used to find embedded type information. The current implementation of $type_constant2 does not include the "*" unicode character, which is used to highlight inline literals in the documentation. This causes a Sphinx error when the inline literal end-string is used in the documentation.

This commit follows the pattern of the commit
8aaf297a0dd6 ("docs: scripts: kernel-doc: accept bitwise negation like ~@var") and takes inspiration from the following commit
69fc23efc7e5 ("kernel-doc: Add unary operator * to $type_param_ref").

Thanks Akira, for your suggestions, I have made the required changes. I am fairly new to the kernel community, so if I am making any mistakes while making patches and replying to mails, please let me know, it will be very helpful.

---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index cb1be22afc65..58129b1cf3f4 100755
@@ -62,7 +62,7 @@ my $anon_struct_union = 0;
 
 # match expressions used to find embedded type information
 my $type_constant = '\b``([^\`]+)``\b';
-my $type_constant2 = '\%([-_\w]+)';
+my $type_constant2 = '\%([-_*\w]+)';
 my $type_func = '(\w+)\(\)';
 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
 my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';

base-commit: 4d2008430ce87061c9cefd4f83daf2d5bb323a96

2.34.1

So I need to look a bit further at the actual change, but I do have a couple of comments on the patch itself. First, the text above is a reasonable description of the problem, as a changelog should have. That said, the subject line could be a bit shorter and to the point.

This text below:

...doesn't belong in the changelog. If you put comments like this below the "---" line, then the maintainer won't have to edit them out when applying the patch.

Did Akira offer you that Reviewed-by tag? I haven't seen it (which doesn't mean it didn't happen). If it was not explicitly given to you, though, you cannot put it here.

Thanks,

jon

Hi Utkarsh,

First of all, thank you for taking the time!

Besides Jon's comments on the summary and changelog, please find my suggestion below.

I'm afraid your description of what is wrong is not clear enough ... Let me talk using some examples.

Current kernel-doc (script) conversion to reST:

    %WQ_* -->  ``WQ_``*

Against which Sphinx complains:

WARNING: Inline literal start-string without end-string.

, because ``* is not recognized as end-string (of inline literal).

With your change applied, conversion to reST becomes:

    %WQ_* --> ``WQ_*``

, and it is a proper inline literal.

Please update the changelog accordingly.

This is not urgent at all. Please take your time and read through Documentation/process/submitting-patches.rst (among others) before submitting v3.

Feel free to add (in v3):

Thanks, Akira

Hello,

There was a slightly different patch submission on the same issue the other day. You might be interested in seeing my response to it [1].

[1]: https://lore.kernel.org/r/[email protected]/

Quoting below for your convenience:

Unfortunately, there's been no patch submission in this direction so far. I'd be delighted if you can try this approach instead.

Thanks, Akira

The kernel-doc script uses the $type_constant2 variable to match expressions used to find embedded type information. The current implementation of $type_constant2 does not include the "*" unicode character, which is used to highlight inline literals in the documentation. This causes a Sphinx error when the inline literal end-string is used in the documentation.

This commit follows the pattern of the commit
8aaf297a0dd6 ("docs: scripts: kernel-doc: accept bitwise negation like ~@var") and takes inspiration from the following commit
69fc23efc7e5 ("kernel-doc: Add unary operator * to $type_param_ref").

Thanks Akira, for your suggestions, I have made the required changes. I am fairly new to the kernel community, so if I am making any mistakes while making patches and replying to mails, please let me know, it will be very helpful.
Sorry, I mailed without adding the previous replies in the mail.

---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index cb1be22afc65..58129b1cf3f4 100755
@@ -62,7 +62,7 @@ my $anon_struct_union = 0;
 
 # match expressions used to find embedded type information
 my $type_constant = '\b``([^\`]+)``\b';
-my $type_constant2 = '\%([-_\w]+)';
+my $type_constant2 = '\%([-_*\w]+)';
 my $type_func = '(\w+)\(\)';
 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
 my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';

base-commit: 4d2008430ce87061c9cefd4f83daf2d5bb323a96

2.34.1