Em Thu, 25 Mar 2021 10:47:11 -0600
Rob Herring [off-list ref] 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 <redacted>
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