1. 25 Feb, 2018 1 commit
    • Will Deacon's avatar
      scripts/kernel-doc: Don't fail with status != 0 if error encountered with -none · 9537ff76
      Will Deacon authored
      
      [ Upstream commit e814bccb ]
      
      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>
      Signed-off-by: default avatarSasha Levin <alexander.levin@verizon.com>
      Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
      9537ff76
  2. 22 Feb, 2018 1 commit
  3. 30 Aug, 2017 1 commit
  4. 03 Jul, 2017 1 commit
  5. 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: Masahiro Yamada's avatarMasahiro Yamada <yamada.masahiro@socionext.com>
      cb77f0d6
  6. 02 Apr, 2017 2 commits
  7. 26 Jan, 2017 1 commit
  8. 13 Jan, 2017 1 commit
  9. 04 Jan, 2017 5 commits
  10. 16 Nov, 2016 1 commit
    • Jani Nikula's avatar
      kernel-doc: add support for one line inline struct member doc comments · 0c9aa209
      Jani Nikula authored
      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: default avatarJani Nikula <jani.nikula@intel.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      0c9aa209
  11. 28 Oct, 2016 1 commit
  12. 06 Sep, 2016 2 commits
  13. 01 Sep, 2016 2 commits
    • Mauro Carvalho Chehab's avatar
      docs-rst: kernel-doc: fix typedef output in RST format · 82801d06
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      82801d06
    • Mauro Carvalho Chehab's avatar
      docs-rst: improve typedef parser · d37c43ce
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      d37c43ce
  14. 24 Aug, 2016 1 commit
    • Mauro Carvalho Chehab's avatar
      docs-rst: kernel-doc: better output struct members · 6d232c80
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      6d232c80
  15. 22 Aug, 2016 1 commit
  16. 23 Jul, 2016 1 commit
  17. 22 Jul, 2016 1 commit
    • Mauro Carvalho Chehab's avatar
      doc-rst: kernel-doc: fix handling of address_space tags · a88b1672
      Mauro Carvalho Chehab authored
      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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      a88b1672
  18. 18 Jul, 2016 1 commit
  19. 03 Jul, 2016 2 commits
    • Mauro Carvalho Chehab's avatar
      doc-rst: linux_tv: remove trailing comments · 64e49546
      Mauro Carvalho Chehab authored
      The conversion script added some comments at the end.
      They point to the original DocBook files, with will be
      removed after the manual fixes. So, they'll be pointing
      to nowere. So, remove those comments.
      
      They'll be forever stored at the Kernel tree. So, if
      someone wants the references, it is just a matter of
      looking at the backlog.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      64e49546
    • Mauro Carvalho Chehab's avatar
      doc-rst: linux_tv: supress lots of warnings · b7e67f6c
      Mauro Carvalho Chehab authored
      The c language parser checks if there are duplicated object
      definitions. That causes lots of warnings like:
      	WARNING: duplicate C object description of ioctl
      
      Let's remove those by telling Sphinx that the language for
      those objects are c++. The look of the descriptions will
      be close, and the warnings will be gone.
      
      Please notice that we had to keep a few of them as C, as
      the c++ parser seems to be broken when it finds an enum.
      
      Yet, this reduced from 219 warnings to 143, with is
      a good thing.
      Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
      b7e67f6c
  20. 10 Jun, 2016 6 commits
  21. 09 Jun, 2016 1 commit
  22. 04 Jun, 2016 1 commit
    • Daniel Vetter's avatar
      scripts/kernel-doc: Add option to inject line numbers · 0b0f5f29
      Daniel Vetter authored
      Opt-in since this wreaks the rst output and must be removed
      by consumers again. This is useful to adjust the linenumbers
      for included kernel-doc snippets in shinx. With that sphinx
      error message will be accurate when there's issues with the
      rst-ness of the kernel-doc comments.
      
      Especially when transitioning a new docbook .tmpl to .rst this
      is extremely useful, since you can just use your editors compilation
      quickfix list to accurately jump from error to error.
      
      v2:
      - Also make sure that we filter the LINENO for purpose/at declaration
        start so it only shows for selected blocks, not all of them (Jani).
        While at it make it a notch more accurate.
      - Avoid undefined $lineno issues. I tried filtering these out at the
        callsite, but Jani spotted more when linting the entire kernel.
        Unamed unions and similar things aren't stored consistently and end
        up with an undefined line number (but also no kernel-doc text, just
        the parameter type). Simplify things and filter undefined line
        numbers in print_lineno() to catch them all.
      
      v3: Fix LINENO 0 issue for kernel-doc comments without @param: lines
      or any other special sections that directly jump to the description
      after the "name - purpose" line. Only really possible for functions
      without parameters. Noticed by Jani.
      
      Cc: Jani Nikula <jani.nikula@intel.com>
      Cc: linux-doc@vger.kernel.org
      Cc: Jonathan Corbet <corbet@lwn.net>
      Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
      Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      0b0f5f29
  23. 03 Jun, 2016 2 commits
  24. 30 May, 2016 3 commits
    • Jani Nikula's avatar
      kernel-doc: reset contents and section harder · 2f4ad40a
      Jani Nikula authored
      If the documentation comment does not have params or sections, the
      section heading may leak from the previous documentation comment.
      Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      2f4ad40a
    • Jani Nikula's avatar
      kernel-doc: concatenate contents of colliding sections · 32217761
      Jani Nikula authored
      If there are multiple sections with the same section name, the current
      implementation results in several sections by the same heading, with the
      content duplicated from the last section to all. Even if there's the
      error message, a more graceful approach is to combine all the
      identically named sections into one, with concatenated contents.
      
      With the supported sections already limited to select few, there are
      massively fewer collisions than there used to be, but this is still
      useful for e.g. when function parameters are documented in the middle of
      a documentation comment, with description spread out above and
      below. (This is not a recommended documentation style, but used in the
      kernel nonetheless.)
      
      We can now also demote the error to a warning.
      Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      32217761
    • Jani Nikula's avatar
      kernel-doc: limit the "section header:" detection to a select few · f624adef
      Jani Nikula authored
      kernel-doc currently identifies anything matching "section header:"
      (specifically a string of word characters and spaces followed by a
      colon) as a new section in the documentation comment, and renders the
      section header accordingly.
      
      Unfortunately, this turns all uses of colon into sections, mostly
      unintentionally. Considering the output, erroneously creating sections
      when not intended is always worse than erroneously not creating sections
      when intended. For example, a line with "http://example.com" turns into
      a "http" heading followed by "//example.com" in normal text style, which
      is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even
      if "WARNING" does not turn into a heading.
      
      It is virtually impossible to change all the kernel-doc comments, either
      way. The compromise is to pick the most commonly used and depended on
      section headers (with variants) and accept them as section headers.
      
      The accepted section headers are, case insensitive:
      
       * description:
       * context:
       * return:
       * returns:
      
      Additionally, case sensitive:
      
       * @return:
      
      All of the above are commonly used in the kernel-doc comments, and will
      result in worse output if not identified as section headers. Also,
      kernel-doc already has some special handling for all of them, so there's
      nothing particularly controversial in adding more special treatment for
      them.
      
      While at it, improve the whitespace handling surrounding section
      names. Do not consider the whitespace as part of the name.
      Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      f624adef