summaryrefslogtreecommitdiffstats
path: root/Documentation/doc-guide
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@s-opensource.com>2017-12-18 10:30:13 -0200
committerJonathan Corbet <corbet@lwn.net>2017-12-21 13:41:46 -0700
commit8ad72163165265b686902c182c1b4a913e738a81 (patch)
treebdff1072d4c1f13cb35e2411adb9a960871cc589 /Documentation/doc-guide
parent7c9aa0157ef4b4cc28c98b08a971dc8344e64aab (diff)
downloadlinux-stable-8ad72163165265b686902c182c1b4a913e738a81.tar.gz
linux-stable-8ad72163165265b686902c182c1b4a913e738a81.tar.bz2
linux-stable-8ad72163165265b686902c182c1b4a913e738a81.zip
scripts: kernel-doc: parse next structs/unions
There are several places within the Kernel tree with nested structs/unions, like this one: struct ingenic_cgu_clk_info { const char *name; enum { CGU_CLK_NONE = 0, CGU_CLK_EXT = BIT(0), CGU_CLK_PLL = BIT(1), CGU_CLK_GATE = BIT(2), CGU_CLK_MUX = BIT(3), CGU_CLK_MUX_GLITCHFREE = BIT(4), CGU_CLK_DIV = BIT(5), CGU_CLK_FIXDIV = BIT(6), CGU_CLK_CUSTOM = BIT(7), } type; int parents[4]; union { struct ingenic_cgu_pll_info pll; struct { struct ingenic_cgu_gate_info gate; struct ingenic_cgu_mux_info mux; struct ingenic_cgu_div_info div; struct ingenic_cgu_fixdiv_info fixdiv; }; struct ingenic_cgu_custom_info custom; }; }; Currently, such struct is documented as: **Definition** :: struct ingenic_cgu_clk_info { const char * name; }; **Members** ``name`` name of the clock With is obvioulsy wrong. It also generates an error: drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum' However, there's nothing wrong with this kernel-doc markup: everything is documented there. It makes sense to document all fields there. So, add a way for the core to parse those structs. With this patch, all documented fields will properly generate documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/doc-guide')
-rw-r--r--Documentation/doc-guide/kernel-doc.rst46
1 files changed, 46 insertions, 0 deletions
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 14c226e8154f..722d4525f7cf 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -281,6 +281,52 @@ comment block.
The kernel-doc data structure comments describe each member of the structure,
in order, with the member descriptions.
+Nested structs/unions
+~~~~~~~~~~~~~~~~~~~~~
+
+It is possible to document nested structs unions, like::
+
+ /**
+ * struct nested_foobar - a struct with nested unions and structs
+ * @arg1: - first argument of anonymous union/anonymous struct
+ * @arg2: - second argument of anonymous union/anonymous struct
+ * @arg3: - third argument of anonymous union/anonymous struct
+ * @arg4: - fourth argument of anonymous union/anonymous struct
+ * @bar.st1.arg1 - first argument of struct st1 on union bar
+ * @bar.st1.arg2 - second argument of struct st1 on union bar
+ * @bar.st2.arg1 - first argument of struct st2 on union bar
+ * @bar.st2.arg2 - second argument of struct st2 on union bar
+ struct nested_foobar {
+ /* Anonymous union/struct*/
+ union {
+ struct {
+ int arg1;
+ int arg2;
+ }
+ struct {
+ void *arg3;
+ int arg4;
+ }
+ }
+ union {
+ struct {
+ int arg1;
+ int arg2;
+ } st1;
+ struct {
+ void *arg1;
+ int arg2;
+ } st2;
+ } bar;
+ };
+
+.. note::
+
+ #) When documenting nested structs or unions, if the struct/union ``foo``
+ is named, the argument ``bar`` inside it should be documented as
+ ``@foo.bar:``
+ #) When the nested struct/union is anonymous, the argument ``bar`` on it
+ should be documented as ``@bar:``
Typedef documentation
---------------------