Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Thu, 25 Mar 2021 18:46:15 +0100
From:   Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To:     Rob Herring <robh@kernel.org>
Cc:     devicetree@vger.kernel.org, linux-kernel@vger.kernel.org,
        Frank Rowand <frowand.list@gmail.com>,
        Lee Jones <lee.jones@linaro.org>,
        Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org
Subject: Re: [PATCH 6/8] of: Fix kerneldoc output formatting
Message-ID: <20210325184615.08526aed@coco.lan>
In-Reply-To: <20210325164713.1296407-7-robh@kernel.org>
References: <20210325164713.1296407-1-robh@kernel.org>
        <20210325164713.1296407-7-robh@kernel.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

Em Thu, 25 Mar 2021 10:47:11 -0600
Rob Herring <robh@kernel.org> escreveu:

> The indentation of the kerneldoc comments affects the output formatting.
> Leading tabs in particular don't work, and sections need to be indented
> under the section header.
> 
> The example snippets for DT source in the comments still have some
> formatting issues, but there doesn't seem to be any way to do multi-line
> literal blocks in kerneldoc.
> 
> Cc: Frank Rowand <frowand.list@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
> Signed-off-by: Rob Herring <robh@kernel.org>
> ---
> 
> Note the dts examples still cause warnings. I couldn't find any way to 
> do a literal block and fix them. Minimally, there needs to be a way to 
> escape ':' and not create sections:
> 
> Documentation/devicetree/kernel-api:11: ../drivers/of/base.c:1466: WARNING: Definition list ends without a blank line; unexpected unindent.

You can do something like this:

/**
 * of_parse_phandle_with_args() - Find a node pointed by phandle in a list
 * @np:		pointer to a device tree node containing a list
 * @list_name:	property name that contains a list
 * @cells_name:	property name that specifies phandles' arguments count
 * @index:	index of a phandle to parse out
 * @out_args:	optional pointer to output arguments structure (will be filled)
 *
 * This function is useful to parse lists of phandles and their arguments.
 * Returns 0 on success and fills out_args, on error returns appropriate
 * errno value.
 *
 * Caller is responsible to call of_node_put() on the returned out_args->np
 * pointer.
 *
 * For example::
 *
 *	phandle1: node1 {
 *		#list-cells = <2>;
 *	};
 *
 *	phandle2: node2 {
 *		#list-cells = <1>;
 *	};
 *
 *	node3 {
 *		list = <&phandle1 1 2 &phandle2 3>;
 *	};
 *
 * To get a device_node of the ``node2`` node you may call this:
 * of_parse_phandle_with_args(node3, "list", "#list-cells", 1, &args);
 */


The problem is that using just:

/**
 ...
 * Example::
 ...

Would make confusion with an existing regex at kernel-doc script that
parses a regex similar to this:

	\*\s+(\w+):

Into:
	**$1**

So, using two words fix the issue.

Granted, this is something that could be improved at kernel-doc with
something like (untested):

<snip>
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index cb92d0e1e932..cea82e004fce 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -392,7 +392,7 @@ my $doc_com_body = '\s*\* ?';
 my $doc_decl = $doc_com . '(\w+)';
 # @params and a strictly limited set of supported section names
 my $doc_sect = $doc_com .
-    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
+    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:]*)$';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 my $doc_inline_start = '^\s*/\*\*\s*$';
</snip>

I'll run some tests if the above works and submit a separate patch
addressing it, likely tomorrow.

Thanks,
Mauro