1. 02 1月, 2018 1 次提交
  2. 22 12月, 2017 11 次提交
    • M
      scripts: kernel-doc: apply filtering rules to warnings · 2defb272
      Mauro Carvalho Chehab 提交于
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      2defb272
    • M
      scripts: kernel-doc: improve nested logic to handle multiple identifiers · 84ce5b98
      Mauro Carvalho Chehab 提交于
      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: NMarkus Heiser <markus.heiser@darmarit.de>
      Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      84ce5b98
    • M
      scripts: kernel-doc: handle nested struct function arguments · 7c0d7e87
      Mauro Carvalho Chehab 提交于
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      7c0d7e87
    • M
      scripts: kernel-doc: print the declaration name on warnings · 151c468b
      Mauro Carvalho Chehab 提交于
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      151c468b
    • M
      scripts: kernel-doc: get rid of $nested parameter · 1081de2d
      Mauro Carvalho Chehab 提交于
      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: NMarkus Heiser <markus.heiser@darmarit.de>
      Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      1081de2d
    • M
      scripts: kernel-doc: parse next structs/unions · 8ad72163
      Mauro Carvalho Chehab 提交于
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      8ad72163
    • M
      scripts: kernel-doc: replace tabs by spaces · 7c9aa015
      Mauro Carvalho Chehab 提交于
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      7c9aa015
    • M
      scripts: kernel-doc: change default to ReST format · bdfe2be3
      Mauro Carvalho Chehab 提交于
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      bdfe2be3
    • M
      scripts: kernel-doc: improve argument handling · b031ac4e
      Mauro Carvalho Chehab 提交于
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      b031ac4e
    • M
      scripts: kernel-doc: get rid of unused output formats · b0514267
      Mauro Carvalho Chehab 提交于
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Acked-by: NJani Nikula <jani.nikula@intel.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      b0514267
    • M
      docs: get rid of kernel-doc-nano-HOWTO.txt · 857af3b7
      Mauro Carvalho Chehab 提交于
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      857af3b7
  3. 12 12月, 2017 1 次提交
    • M
      kernel-doc: parse DECLARE_KFIFO and DECLARE_KFIFO_PTR() · 45005b27
      Mauro Carvalho Chehab 提交于
      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: NRandy Dunlap <rdunlap@infradead.org>
      Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Tested-by: NRandy Dunlap <rdunlap@infradead.org>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      45005b27
  4. 02 12月, 2017 1 次提交
    • W
      scripts/kernel-doc: Don't fail with status != 0 if error encountered with -none · e814bccb
      Will Deacon 提交于
      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: NWill Deacon <will.deacon@arm.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      e814bccb
  5. 21 11月, 2017 1 次提交
    • M
      Add optional check for bad kernel-doc comments · 3a025e1d
      Matthew Wilcox 提交于
      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: NMatthew Wilcox <mawilcox@microsoft.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      3a025e1d
  6. 16 11月, 2017 1 次提交
  7. 27 9月, 2017 1 次提交
  8. 31 8月, 2017 1 次提交
  9. 03 7月, 2017 1 次提交
  10. 14 5月, 2017 1 次提交
    • K
      scripts: Switch to more portable Perl shebang · cb77f0d6
      Kamil Rytarowski 提交于
      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: NKamil Rytarowski <n54@gmx.com>
      Signed-off-by: NMasahiro Yamada <yamada.masahiro@socionext.com>
      cb77f0d6
  11. 03 4月, 2017 2 次提交
  12. 27 1月, 2017 1 次提交
  13. 14 1月, 2017 1 次提交
  14. 05 1月, 2017 5 次提交
  15. 17 11月, 2016 1 次提交
    • J
      kernel-doc: add support for one line inline struct member doc comments · 0c9aa209
      Jani Nikula 提交于
      kernel-doc supports documenting struct members "inline" since
      a4c6ebed ("scripts/kernel-doc Allow struct arguments documentation
      in struct body"). This requires the inline kernel-doc comments to have
      the opening and closing comment markers (/** and */ respectively) on
      lines of their own, even for short comments. For example:
      
      	/**
      	 * struct foo - struct documentation
      	 */
      	struct foo {
      		/**
      		 * @bar: member documentation
      		 */
      		int bar;
      	};
      
      Add support for one line inline comments:
      
      	/**
      	 * struct foo - struct documentation
      	 */
      	struct foo {
      		/** @bar: member documentation */
      		int bar;
      	};
      
      Note that mixing of the two in one doc comment is not allowed; either
      both comment markers must be on lines of their own, or both must be on
      the one line. This limitation keeps both the comments more uniform, and
      kernel-doc less complicated.
      
      Cc: Daniel Vetter <daniel@ffwll.ch>
      Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      0c9aa209
  16. 29 10月, 2016 1 次提交
  17. 06 9月, 2016 2 次提交
  18. 01 9月, 2016 2 次提交
    • M
      docs-rst: kernel-doc: fix typedef output in RST format · 82801d06
      Mauro Carvalho Chehab 提交于
      When using a typedef function like this one:
      	typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);
      
      The Sphinx C domain expects it to create a c:type: reference,
      as that's the way it creates the type references when parsing
      a c:function:: declaration.
      
      So, a declaration like:
      
      	.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)
      
      Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.
      
      So, when outputting such typedefs in RST format, we need to handle
      this special case, as otherwise it will produce those warnings:
      
      	./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
      	./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
      	./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
      
      So, change the kernel-doc script to produce a RST output for the
      above typedef as:
      	.. c:type:: v4l2_check_dv_timings_fnc
      
      	   **Typedef**: timings check callback
      
      	**Syntax**
      
      	  ``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``
      Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      82801d06
    • M
      docs-rst: improve typedef parser · d37c43ce
      Mauro Carvalho Chehab 提交于
      Improve the parser to handle typedefs like:
      
      	typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);
      Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      d37c43ce
  19. 25 8月, 2016 1 次提交
    • M
      docs-rst: kernel-doc: better output struct members · 6d232c80
      Mauro Carvalho Chehab 提交于
      Right now, for a struct, kernel-doc produces the following output:
      
      	.. c:type:: struct v4l2_prio_state
      
      	   stores the priority states
      
      	**Definition**
      
      	::
      
      	  struct v4l2_prio_state {
      	    atomic_t prios[4];
      	  };
      
      	**Members**
      
      	``atomic_t prios[4]``
      	  array with elements to store the array priorities
      
      Putting a member name in verbatim and adding a continuation line
      causes the LaTeX output to generate something like:
      	item[atomic_t prios\[4\]] array with elements to store the array priorities
      
      Everything inside "item" is non-breakable, with may produce
      lines bigger than the column width.
      
      Also, for function members, like:
      
              int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num);
      
      It puts the name of the member at the end, like:
      
              int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read
      
      With is very confusing.
      
      The best is to highlight what really matters: the member name.
      is a secondary information.
      
      So, change kernel-doc, for it to produce the output on a different way:
      
      	**Members**
      
      	``prios[4]``
      
      	  array with elements to store the array priorities
      
      Also, as the type is not part of LaTeX "item[]", LaTeX will split it into
      multiple lines, if needed.
      
      So, both LaTeX/PDF and HTML outputs will look good.
      
      It should be noticed, however, that the way Sphinx LaTeX output handles
      things like:
      
      	Foo
      	   bar
      
      is different than the HTML output. On HTML, it will produce something
      like:
      
      	**Foo**
      	   bar
      
      While, on LaTeX, it puts both foo and bar at the same line, like:
      
      	**Foo** bar
      Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      6d232c80
  20. 23 8月, 2016 1 次提交
  21. 23 7月, 2016 2 次提交
    • M
      doc-rst: kernel-doc: fix a change introduced by mistake · a3f57ad0
      Mauro Carvalho Chehab 提交于
      changeset b7e67f6c ("doc-rst: linux_tv: supress lots of warnings")
      were meant to touch only on media files, but it also touched
      at this script by mistake. Revert such change.
      Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      a3f57ad0
    • M
      doc-rst: kernel-doc: fix handling of address_space tags · a88b1672
      Mauro Carvalho Chehab 提交于
      The RST cpp:function handler is very pedantic: it doesn't allow any
      macros like __user on it:
      
      	Documentation/media/kapi/dtv-core.rst:28: WARNING: Error when parsing function declaration.
      	If the function has no return type:
      	  Error in declarator or parameters and qualifiers
      	  Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8]
      	    ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
      	    --------^
      	If the function has a return type:
      	  Error in declarator or parameters and qualifiers
      	  If pointer to member declarator:
      	    Invalid definition: Expected '::' in pointer to member (function). [error at 37]
      	      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
      	      -------------------------------------^
      	  If declarator-id:
      	    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102]
      	      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
      	      ------------------------------------------------------------------------------------------------------^
      
      So, we have to remove it from the function prototype.
      Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      a88b1672
  22. 18 7月, 2016 1 次提交