user/sven/linux.git/scripts/kernel-doc, branch v4.16.18

scripts: kernel_doc: better handle show warnings logic

2018-01-01T19:49:07Z

The logic with inhibits warnings for definitions that is not output is incomplete: it doesn't cover the cases where OUTPUT_INTERNAL and OUTPUT_EXPORTED are used. As the most common case is OUTPUT_ALL, place it first, in order to optimize a litte bit the check logic. Fixes: 2defb2729217 ("scripts: kernel-doc: apply filtering rules to warnings") Reported-by: Randy Dunlap Acked-and-Tested-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

scripts: kernel-doc: apply filtering rules to warnings

2017-12-21T20:41:47Z

When kernel-doc is called with output selection filters, it will be called lots of time for a single file. If there is a warning present there, it means that it may print hundreds of identical warnings. Worse than that, the -function NAME actually filters only functions. So, it makes no sense at all to print warnings for structs or enums. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

scripts: kernel-doc: improve nested logic to handle multiple identifiers

2017-12-21T20:41:47Z

It is possible to use nested structs like: struct { struct { void *arg1; } st1, st2, *st3, st4; }; Handling it requires to split each parameter. Change the logic to allow such definitions. In order to test the new nested logic, the following file was used to test


struct foo { int a; }; /* Just to avoid errors if compiled */

/**
 * struct my_struct - a struct with nested unions and structs
 * @arg1: first argument of anonymous union/anonymous struct
 * @arg2: second argument of anonymous union/anonymous struct
 * @arg1b: first argument of anonymous union/anonymous struct
 * @arg2b: 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.st1.bar1: bar1 at st1
 * @bar.st1.bar2: bar2 at st1
 * @bar.st2.arg1: first argument of struct st2 on union bar
 * @bar.st2.arg2: second argument of struct st2 on union bar
 * @bar.st3.arg2: second argument of struct st3 on union bar
 * @f1: nested function on anonimous union/struct
 * @bar.st2.f2: nested function on named union/struct
 */
struct my_struct {
   /* Anonymous union/struct*/
   union {
	struct {
	    char arg1 : 1;
	    char arg2 : 3;
	};
       struct {
           int arg1b;
           int arg2b;
       };
       struct {
           void *arg3;
           int arg4;
           int (*f1)(char foo, int bar);
       };
   };
   union {
       struct {
           int arg1;
           int arg2;
	   struct foo bar1, *bar2;
       } st1;           /* bar.st1 is undocumented, cause a warning */
       struct {
           void *arg1;  /* bar.st3.arg1 is undocumented, cause a warning */
	    int arg2;
          int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
       } st2, st3, *st4;
       int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
   } bar;               /* bar is undocumented, cause a warning */

   /* private: */
   int undoc_privat;    /* is undocumented but private, no warning */

   /* public: */
   int undoc_public;    /* is undocumented, cause a warning */
};

It produces the following warnings, as expected: test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct' Suggested-by: Markus Heiser Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

scripts: kernel-doc: handle nested struct function arguments

2017-12-21T20:41:47Z

Function arguments are different than usual ones. So, an special logic is needed in order to handle such arguments on nested structs. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

scripts: kernel-doc: print the declaration name on warnings

2017-12-21T20:41:47Z

The logic at create_parameterlist()'s ancillary push_parameter() function has already a way to output the declaration name, with would help to discover what declaration is missing. However, currently, the logic is utterly broken, as it uses the var $type with a wrong meaning. With the current code, it will never print anything. I suspect that originally it was using the second argument of output_declaration(). I opted to not rely on a globally defined $declaration_name, but, instead, to pass it explicitly as a parameter. While here, I removed a unaligned check for !$anon_struct_union. This is not needed, as, if $anon_struct_union is not zero, $parameterdescs{$param} will be defined. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

scripts: kernel-doc: get rid of $nested parameter

2017-12-21T20:41:46Z

The check_sections() function has a $nested parameter, meant to identify when a nested struct is present. As we now have a logic that handles it, get rid of such parameter. Suggested-by: Markus Heiser Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

scripts: kernel-doc: parse next structs/unions

2017-12-21T20:41:46Z

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 Signed-off-by: Jonathan Corbet

scripts: kernel-doc: replace tabs by spaces

2017-12-21T20:41:46Z

Sphinx has a hard time dealing with tabs, causing it to misinterpret paragraph continuation. As we're now mainly focused on supporting ReST output, replace tabs by spaces, in order to avoid troubles when the output is parsed by Sphinx. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

scripts: kernel-doc: change default to ReST format

2017-12-21T20:41:46Z

Right now, if kernel-doc is called without arguments, it defaults to man pages. IMO, it makes more sense to default to ReST, as this is the output that it is most used nowadays, and it easier to check if everything got parsed fine on an enriched text mode format. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

scripts: kernel-doc: improve argument handling

2017-12-21T20:41:46Z

Right now, if one uses "--rst" instead of "-rst", it just ignore the argument and produces a man page. Change the logic to accept both "-cmd" and "--cmd". Also, if "cmd" doesn't exist, print the usage information and exit. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet