Received-SPF: pass (google.com: domain of linux-kernel+bounces-59617-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1;
From: Jonathan Corbet <corbet@lwn.net>
To: Tejun Heo <tj@kernel.org>, Waiman Long <longman@redhat.com>
Cc: Lai Jiangshan <jiangshanlai@gmail.com>, linux-kernel@vger.kernel.org
Subject: Re: [PATCH] workqueue: Fix kernel-doc comment of unplug_oldest_pwq()
In-Reply-To: <ZcZSlBRELjUIVJ_B@slm.duckdns.org>
References: <20240209145850.1157304-1-longman@redhat.com>
 <ZcZSlBRELjUIVJ_B@slm.duckdns.org>
Date: Fri, 09 Feb 2024 09:36:50 -0700
Message-ID: <87zfw9d271.fsf@meer.lwn.net>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain

Tejun Heo <tj@kernel.org> writes:

> (cc'ing Jonathan and quoting whole body)
>
> I'm not necessarily against the patch but at least from in-code
> documentation POV the diagram being in the function comment seems better.
> Jonathan, do you happen to know a better way to address this?

So I went to reproduce this problem, but it seems that it's hidden away
in some branch and not in linux-next.  So I'll have to guess without
testing my solution, but...

> On Fri, Feb 09, 2024 at 09:58:50AM -0500, Waiman Long wrote:
>> It turns out that it is not a good idea to put an ASCII diagram in the
>> kernel-doc comment of unplug_oldest_pwq() as the tool puts out warnings
>> about its format and will likely render it illegible anyway. Break the
>> ASCII diagram out into its own comment block inside the function to
>> avoid this problem.
>> 
>> Signed-off-by: Waiman Long <longman@redhat.com>
>> ---
>>  kernel/workqueue.c | 32 ++++++++++++++++++--------------
>>  1 file changed, 18 insertions(+), 14 deletions(-)
>> 
>> diff --git a/kernel/workqueue.c b/kernel/workqueue.c
>> index cd2c6edc5c66..f622f535bc00 100644
>> --- a/kernel/workqueue.c
>> +++ b/kernel/workqueue.c
>> @@ -1790,25 +1790,29 @@ static bool pwq_activate_first_inactive(struct pool_workqueue *pwq, bool fill)
>>   * unplug_oldest_pwq - restart an oldest plugged pool_workqueue
>>   * @wq: workqueue_struct to be restarted
>>   *
>> - * pwq's are linked into wq->pwqs with the oldest first. For ordered
>> - * workqueues, only the oldest pwq is unplugged, the others are plugged to
>> - * suspend execution until the oldest one is drained. When this happens, the
>> - * next oldest one (first plugged pwq in iteration) will be unplugged to
>> - * restart work item execution to ensure proper work item ordering.
>> - *
>> - *    dfl_pwq --------------+     [P] - plugged
>> - *                          |
>> - *                          v
>> - *    pwqs -> A -> B [P] -> C [P] (newest)
>> - *            |    |        |
>> - *            1    3        5
>> - *            |    |        |
>> - *            2    4        6
>> + * This function should only be called for ordered workqueues where only the

The problem here is that you have a literal block without marking it as
such.  If you were to format it as:

> * next oldest one (first plugged pwq in iteration) will be unplugged to
> * restart work item execution to ensure proper work item ordering::
> *
> *    dfl_pwq --------------+     [P] - plugged
> *                          |
> *                          v
> *    pwqs -> A -> B [P] -> C [P] (newest)
> *            |    |        |
> *            1    3        5
> *            |    |        |
> *            2    4        6
> *
> * This function should only be called for ordered workqueues where only the

..it should work.  The changes are the "::" after "ordering" and the
blank line at the end of the block.

Thanks,

jon