• Mauro Carvalho Chehab's avatar
    scripts: kernel-doc: parse next structs/unions · 8ad72163
    Mauro Carvalho Chehab authored
    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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
    Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
    8ad72163
kernel-doc.rst 16.8 KB