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
Signed-off-by: Utkarsh Tripathi <[email protected]>
---
include/linux/workqueue.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/linux/workqueue.h b/include/linux/workqueue.h
index 158784dd189a..b4aebd981a23 100644
--- a/include/linux/workqueue.h
+++ b/include/linux/workqueue.h
@@ -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,
On Wed, 1 May 2024 19:02:40 +0530, Utkarsh Tripathi wrote:
> 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
>
> Signed-off-by: Utkarsh Tripathi <[email protected]>
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:
> In my opinion, reST-specific clutters like these should be avoided in
> kernel-doc comments as far as possible.
>
> Instead, I think you can educate kernel-doc (script) so that "*" is
> allowed in the %CONSTANT pattern, meaning %WQ_* can be converted
> to ``WQ_*`` in reST.
>
> For similar changes made against the @param pattern, see commits
> 69fc23efc7e5 ("kernel-doc: Add unary operator * to $type_param_ref")
> and 8aaf297a0dd6 ("docs: scripts: kernel-doc: accept bitwise negation
> like ~@var").
>
> I guess it is $type_constant2 that needs a tweak in this case.
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.
Signed-off-by: Utkarsh Tripathi <[email protected]>
Reviewed-by: Akira Yokosawa <[email protected]>
Suggested-by: Akira Yokosawa <[email protected]>
---
scripts/kernel-doc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index cb1be22afc65..58129b1cf3f4 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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
Hello,
On Wed, 1 May 2024 19:02:40 +0530, Utkarsh Tripathi wrote:
> 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
>
> Signed-off-by: Utkarsh Tripathi <[email protected]>
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:
> In my opinion, reST-specific clutters like these should be avoided in
> kernel-doc comments as far as possible.
>
> Instead, I think you can educate kernel-doc (script) so that "*" is
> allowed in the %CONSTANT pattern, meaning %WQ_* can be converted
> to ``WQ_*`` in reST.
>
> For similar changes made against the @param pattern, see commits
> 69fc23efc7e5 ("kernel-doc: Add unary operator * to $type_param_ref")
> and 8aaf297a0dd6 ("docs: scripts: kernel-doc: accept bitwise negation
> like ~@var").
>
> I guess it is $type_constant2 that needs a tweak in this case.
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.
Signed-off-by: Utkarsh Tripathi <[email protected]>
Reviewed-by: Akira Yokosawa <[email protected]>
Suggested-by: Akira Yokosawa <[email protected]>
---
scripts/kernel-doc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index cb1be22afc65..58129b1cf3f4 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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
Utkarsh Tripathi <[email protected]> writes:
> 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.
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:
> 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.
..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.
> Signed-off-by: Utkarsh Tripathi <[email protected]>
> Reviewed-by: Akira Yokosawa <[email protected]>
> Suggested-by: Akira Yokosawa <[email protected]>
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.
On Wed, 1 May 2024 23:27:30 +0530, Utkarsh Tripathi wrote:
> 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.
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):
Reviewed-by: Akira Yokosawa <[email protected]>
Thanks, Akira