Em Thu, 25 Mar 2021 10:47:11 -0600
Rob Herring <robh@xxxxxxxxxx> 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@xxxxxxxxx>
> Cc: Mauro Carvalho Chehab <mchehab@xxxxxxxxxx>
> Signed-off-by: Rob Herring <robh@xxxxxxxxxx>
> ---
>
> 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
