An error occurred fetching the project authors.
  1. 25 Nov, 2018 1 commit
  2. 07 Nov, 2018 2 commits
  3. 18 Oct, 2018 1 commit
    • Randy Dunlap's avatar
      kernel-doc: fix declaration type determination · cf419d54
      Randy Dunlap authored
      Make declaration type determination more robust.
      
      When scripts/kernel-doc is deciding if some kernel-doc notation
      contains an enum, a struct, a union, a typedef, or a function,
      it does a pattern match on the beginning of the string, looking
      for a match with one of "struct", "union", "enum", or "typedef",
      and otherwise defaults to a function declaration type.
      However, if a function or a function-like macro has a name that
      begins with "struct" (e.g., struct_size()), then kernel-doc
      incorrectly decides that this is a struct declaration.
      
      Fix this by looking for the declaration type keywords having an
      ending word boundary (\b), so that "struct_size" will not match
      a struct declaration.
      
      I compared lots of html before/after output from core-api, driver-api,
      and networking.  There were no differences in any of the files that
      I checked.
      Signed-off-by: default avatarRandy Dunlap <rdunlap@infradead.org>
      Acked-by: default avatarJani Nikula <jani.nikula@intel.com>
      Tested-by: default avatarKees Cook <keescook@chromium.org>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      cf419d54
  4. 06 Aug, 2018 1 commit
  5. 23 Jul, 2018 1 commit
  6. 29 Mar, 2018 1 commit
  7. 21 Mar, 2018 1 commit
  8. 20 Feb, 2018 1 commit
  9. 18 Feb, 2018 2 commits
  10. 15 Feb, 2018 8 commits
  11. 01 Jan, 2018 1 commit
  12. 21 Dec, 2017 11 commits
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: apply filtering rules to warnings · 2defb272
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      2defb272
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: improve nested logic to handle multiple identifiers · 84ce5b98
      Mauro Carvalho Chehab authored
      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
      
      <code>
      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 */
      };
      </code>
      
      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: default avatarMarkus Heiser <markus.heiser@darmarit.de>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      84ce5b98
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: handle nested struct function arguments · 7c0d7e87
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      7c0d7e87
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: print the declaration name on warnings · 151c468b
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      151c468b
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: get rid of $nested parameter · 1081de2d
      Mauro Carvalho Chehab authored
      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: default avatarMarkus Heiser <markus.heiser@darmarit.de>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      1081de2d
    • 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
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: replace tabs by spaces · 7c9aa015
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      7c9aa015
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: change default to ReST format · bdfe2be3
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      bdfe2be3
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: improve argument handling · b031ac4e
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      b031ac4e
    • Mauro Carvalho Chehab's avatar
      scripts: kernel-doc: get rid of unused output formats · b0514267
      Mauro Carvalho Chehab authored
      Since there isn't any docbook code anymore upstream,
      we can get rid of several output formats:
      
      - docbook/xml, html, html5 and list formats were used by
        the old build system;
      - As ReST is text, there's not much sense on outputting
        on a different text format.
      
      After this patch, only man and rst output formats are
      supported.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Acked-by: default avatarJani Nikula <jani.nikula@intel.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      b0514267
    • Mauro Carvalho Chehab's avatar
      docs: get rid of kernel-doc-nano-HOWTO.txt · 857af3b7
      Mauro Carvalho Chehab authored
      Everything there is already described at
      Documentation/doc-guide/kernel-doc.rst. So, there's no reason why
      to keep it anymore.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      857af3b7
  13. 11 Dec, 2017 1 commit
    • Mauro Carvalho Chehab's avatar
      kernel-doc: parse DECLARE_KFIFO and DECLARE_KFIFO_PTR() · 45005b27
      Mauro Carvalho Chehab authored
      On media, we now have an struct declared with:
      
      struct lirc_fh {
              struct list_head list;
              struct rc_dev *rc;
              int                             carrier_low;
              bool                            send_timeout_reports;
              DECLARE_KFIFO_PTR(rawir, unsigned int);
              DECLARE_KFIFO_PTR(scancodes, struct lirc_scancode);
              wait_queue_head_t               wait_poll;
              u8                              send_mode;
              u8                              rec_mode;
      };
      
      gpiolib.c has a similar declaration with DECLARE_KFIFO().
      
      Currently, those produce the following error:
      
      	./include/media/rc-core.h:96: warning: No description found for parameter 'int'
      	./include/media/rc-core.h:96: warning: No description found for parameter 'lirc_scancode'
      	./include/media/rc-core.h:96: warning: Excess struct member 'rawir' description in 'lirc_fh'
      	./include/media/rc-core.h:96: warning: Excess struct member 'scancodes' description in 'lirc_fh'
      	../drivers/gpio/gpiolib.c:601: warning: No description found for parameter '16'
      	../drivers/gpio/gpiolib.c:601: warning: Excess struct member 'events' description in 'lineevent_state'
      
      So, teach kernel-doc how to parse DECLARE_KFIFO() and DECLARE_KFIFO_PTR().
      
      While here, relax at the past DECLARE_foo() macros, accepting a random
      number of spaces after comma.
      
      The addition of DECLARE_KFIFO() was
      Suggested-by: default avatarRandy Dunlap <rdunlap@infradead.org>
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Tested-by: default avatarRandy Dunlap <rdunlap@infradead.org>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      45005b27
  14. 02 Dec, 2017 1 commit
    • Will Deacon's avatar
      scripts/kernel-doc: Don't fail with status != 0 if error encountered with -none · e814bccb
      Will Deacon authored
      My bisect scripts starting running into build failures when trying to
      compile 4.15-rc1 with the builds failing with things like:
      
      drivers/net/wireless/broadcom/brcm80211/brcmfmac/sdio.c:2078: error: Cannot parse struct or union!
      
      The line in question is actually just a #define, but after some digging
      it turns out that my scripts pass W=1 and since commit 3a025e1d
      ("Add optional check for bad kernel-doc comments") that results in
      kernel-doc running on each source file. The file in question has a
      badly formatted comment immediately before the #define:
      
      /**
       * struct brcmf_skbuff_cb reserves first two bytes in sk_buff::cb for
       * bus layer usage.
       */
      
      which causes the regex in dump_struct to fail (lack of braces following
      struct declaration) and kernel-doc returns 1, which causes the build
      to fail.
      
      Fix the issue by always returning 0 from kernel-doc when invoked with
      -none. It successfully generates no documentation, and prints out any
      issues.
      
      Cc: Matthew Wilcox <mawilcox@microsoft.com>
      Cc: Jonathan Corbet <corbet@lwn.net>
      Signed-off-by: default avatarWill Deacon <will.deacon@arm.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      e814bccb
  15. 20 Nov, 2017 1 commit
    • Matthew Wilcox's avatar
      Add optional check for bad kernel-doc comments · 3a025e1d
      Matthew Wilcox authored
      Implement a '-none' output mode for kernel-doc which will only output
      warning messages, and suppresses the warning message about there being
      no kernel-doc in the file.
      
      If the build has requested additional warnings, automatically check all
      .c files.  This patch does not check .h files.  Enabling the warning
      by default would add about 1300 warnings, so it's default off for now.
      People who care can use this to check they didn't break the docs and
      maybe we'll get all the warnings fixed and be able to enable this check
      by default in the future.
      Signed-off-by: default avatarMatthew Wilcox <mawilcox@microsoft.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      3a025e1d
  16. 16 Nov, 2017 1 commit
  17. 26 Sep, 2017 1 commit
  18. 30 Aug, 2017 1 commit
  19. 03 Jul, 2017 1 commit
  20. 14 May, 2017 1 commit
    • Kamil Rytarowski's avatar
      scripts: Switch to more portable Perl shebang · cb77f0d6
      Kamil Rytarowski authored
      The default NetBSD package manager is pkgsrc and it installs Perl
      along other third party programs under custom and configurable prefix.
      The default prefix for binary prebuilt packages is /usr/pkg, and the
      Perl executable lands in /usr/pkg/bin/perl.
      
      This change switches "/usr/bin/perl" to "/usr/bin/env perl" as it's
      the most portable solution that should work for almost everybody.
      Perl's executable is detected automatically.
      
      This change switches -w option passed to the executable with more
      modern "use warnings;" approach. There is no functional change to the
      default behavior.
      
      While there, drop "require 5" from scripts/namespace.pl (Perl from 1994?).
      Signed-off-by: default avatarKamil Rytarowski <n54@gmx.com>
      Signed-off-by: default avatarMasahiro Yamada <yamada.masahiro@socionext.com>
      cb77f0d6
  21. 02 Apr, 2017 1 commit