1. 25 Feb, 2018 1 commit
    • Will Deacon's avatar
      scripts/kernel-doc: Don't fail with status != 0 if error encountered with -none · 19ff1dfd
      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@microsoft.com>
      Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
      19ff1dfd
  2. 18 Nov, 2015 1 commit
  3. 11 Oct, 2015 1 commit
  4. 10 Oct, 2015 2 commits
  5. 13 Sep, 2015 3 commits
    • Danilo Cesar Lemes de Paula's avatar
      scripts/kernel-doc: Replacing highlights hash by an array · 4d732701
      Danilo Cesar Lemes de Paula authored
      The "highlight" code is very sensible to the order of the hash keys,
      but the order of the keys cannot be predicted. It generates
      faulty DocBook entries like:
      	- @<function>device_for_each_child</function>
      
      Sorting the result is not enough some times (as it's deterministic but
      we can't control it).
      We should use an array for that job, so we can guarantee that the order
      of the regex execution on dohighlight is correct.
      
      [jc: I think this is kind of papering around the real problem, that people
       are saying @function() when "function" is not a parameter.  But this makes
       things better than they were before, so...]
      Signed-off-by: default avatarDanilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      4d732701
    • Ben Hutchings's avatar
      Documentation: Avoid creating man pages in source tree · 68f86662
      Ben Hutchings authored
      Currently kernel-doc generates a dummy DocBook file when asked to
      convert a C source file with no structured comments.  For an
      out-of-tree build (objtree != srctree), the title of the output file
      is the absolute path name of the C source file, which later results
      in a manual page being created alongside the C source file.
      
      Change the title to be a relative path.
      Signed-off-by: default avatarBen Hutchings <ben@decadent.org.uk>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      68f86662
    • Danilo Cesar Lemes de Paula's avatar
      scripts/kernel-doc: Processing -nofunc for functions only · 23aebb3c
      Danilo Cesar Lemes de Paula authored
      Docproc processes the EXPORT_SYMBOL(f1) macro and uses -nofunc f1 to
      avoid duplicated documentation in the next call.
      It works for most of the cases, but there are some specific situations
      where a struct has the same name of an already-exported function.
      
      Current kernel-doc behavior ignores those structs and does not add them
      to the final documentation. This patch fixes it.
      
      This is unusual, the only case I've found is the drm_modeset_lock
      (function and struct) defined in drm_modeset_lock.h and
      drm_modeset_lock.c. Considering this, it should only affect the DRM
      documentation by including struct drm_modeset_lock to the final Docbook.
      Signed-off-by: default avatarDanilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      23aebb3c
  6. 04 Sep, 2015 1 commit
  7. 23 Aug, 2015 1 commit
  8. 06 Aug, 2015 1 commit
    • Danilo Cesar Lemes de Paula's avatar
      scripts/kernel-doc Allow struct arguments documentation in struct body · a4c6ebed
      Danilo Cesar Lemes de Paula authored
      Describing arguments at top of a struct definition works fine
      for small/medium size structs, but it definitely doesn't work well
      for struct with a huge list of elements.
      
      Keeping the arguments list inside the struct body makes it easier
      to maintain the documentation.
      ie:
      /**
       * struct my_struct - short description
       * @a: first member
       * @b: second member
       *
       * Longer description
       */
      struct my_struct {
          int a;
          int b;
          /**
           * @c: This is longer description of C
           *
           * You can use paragraphs to describe arguments
           * using this method.
           */
          int c;
      };
      
      This patch allows the use of this kind of syntax. Only one argument
      per comment and user can use how many paragraphs he needs. It should
      start with /**, which is already being used by kernel-doc. If those
      comment doesn't follow those rules, it will be ignored.
      Signed-off-by: default avatarDanilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
      Cc: Randy Dunlap <rdunlap@infradead.org>
      Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
      Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
      Cc: Jonathan Corbet <corbet@lwn.net>
      Cc: Herbert Xu <herbert@gondor.apana.org.au>
      Cc: Stephan Mueller <smueller@chronox.de>
      Cc: Michal Marek <mmarek@suse.cz>
      Cc: linux-kernel@vger.kernel.org
      Cc: linux-doc@vger.kernel.org
      Cc: intel-gfx <intel-gfx@lists.freedesktop.org>
      Cc: dri-devel <dri-devel@lists.freedesktop.org>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      a4c6ebed
  9. 10 Jul, 2015 2 commits
  10. 11 Dec, 2014 1 commit
  11. 26 Aug, 2014 1 commit
  12. 12 Jul, 2014 1 commit
  13. 02 Dec, 2013 1 commit
  14. 13 Nov, 2013 1 commit
  15. 06 Nov, 2013 1 commit
  16. 28 Feb, 2013 1 commit
    • Nishanth Menon's avatar
      scripts/kernel-doc: handle struct member __aligned without numbers · 9dc30918
      Nishanth Menon authored
      Commit ef5da59f ("scripts/kernel-doc: handle struct member
      __aligned") permits "char something [123] __aligned(8);".
      
      However, by using \d we constraint ourselves with integers.  This is not
      always the case.  In fact, it might be better to do char something[123]
      __aligned(sizeof(u16));
      
      For example, With wireless_dev defining:
      
          u8 address[ETH_ALEN] __aligned(sizeof(u16));
      
      With \d, scripts/kernel-doc erroneously says:
      
          Warning(include/net/cfg80211.h:2618): Excess struct/union/enum/typedef member 'address' description in 'wireless_dev'
      
      This is because the regex __aligned\s*\(\d+\) fails match at \d as
      sizeof is used.
      
      So replace \d with .  to indicate "something" in kernel-doc to ignore
      __aligned(SOMETHING) in structs.  With this change, we can use integers
      OR sizeof() or macros as we please.
      Signed-off-by: default avatarNishanth Menon <nm@ti.com>
      Cc: Fengguang Wu <fengguang.wu@intel.com>
      Cc: Johannes Berg <johannes.berg@intel.com>
      Cc: Randy Dunlap <rdunlap@infradead.org>
      Cc: Michal Marek <mmarek@suse.cz>
      Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
      Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
      9dc30918
  17. 03 Jan, 2013 1 commit
    • Greg Kroah-Hartman's avatar
      misc: remove __dev* attributes. · 6ae14171
      Greg Kroah-Hartman authored
      CONFIG_HOTPLUG is going away as an option.  As a result, the __dev*
      markings need to be removed.
      
      This change removes the last of the __dev* markings from the kernel from
      a variety of different, tiny, places.
      
      Based on patches originally written by Bill Pemberton, but redone by me
      in order to handle some of the coding style issues better, by hand.
      
      Cc: Bill Pemberton <wfp5p@virginia.edu>
      Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
      6ae14171
  18. 06 Dec, 2012 1 commit
  19. 27 Nov, 2012 1 commit
  20. 05 Oct, 2012 3 commits
    • Daniel Santos's avatar
      kernel-doc: don't mangle whitespace in Example section · 12ae6779
      Daniel Santos authored
      A section with the name "Example" (case-insensitive) has a special meaning
      to kernel-doc.  These sections are output using mono-type fonts.  However,
      leading whitespace is stripped, thus robbing a lot of meaning from this,
      as indented code examples will be mangled.
      
      This patch preserves the leading whitespace for "Example" sections.  More
      accurately, it preserves it for all sections, but removes it later if the
      section isn't an "Example" section.
      Signed-off-by: default avatarDaniel Santos <daniel.santos@pobox.com>
      Cc: Randy Dunlap <rdunlap@xenotime.net>
      Cc: Michal Marek <mmarek@suse.cz>
      Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
      Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
      12ae6779
    • Daniel Santos's avatar
      kernel-doc: bugfix - empty line in Example section · e314ba31
      Daniel Santos authored
      If you have a section named "Example" that contains an empty line,
      attempting to generate htmldocs give you the error:
      
      /path/Documentation/DocBook/kernel-api.xml:3455: parser error : Opening and ending tag mismatch: programlisting line 3449 and para
         </para><para>
                ^
      /path/Documentation/DocBook/kernel-api.xml:3473: parser error : Opening and ending tag mismatch: para line 3467 and programlisting
      </programlisting></informalexample>
                       ^
      /path/Documentation/DocBook/kernel-api.xml:3678: parser error : Opening and ending tag mismatch: programlisting line 3672 and para
         </para><para>
                ^
      /path/Documentation/DocBook/kernel-api.xml:3701: parser error : Opening and ending tag mismatch: para line 3690 and programlisting
      </programlisting></informalexample>
                       ^
      unable to parse
      /path/Documentation/DocBook/kernel-api.xml
      
      Essentially, the script attempts to close a <programlisting> with a
      closing tag for a <para> block.  This patch corrects the problem by
      simply not outputting anything extra when we're dumping pre-formatted
      text, since the empty line will be rendered correctly anyway.
      Signed-off-by: default avatarDaniel Santos <daniel.santos@pobox.com>
      Cc: Randy Dunlap <rdunlap@xenotime.net>
      Cc: Michal Marek <mmarek@suse.cz>
      Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
      Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
      e314ba31
    • Daniel Santos's avatar
      kernel-doc: bugfix - multi-line macros · 65478428
      Daniel Santos authored
      Prior to this patch the following code breaks:
      
      /**
       * multiline_example - this breaks kernel-doc
       */
       #define multiline_example( \
      myparam)
      
      Producing this error:
      
      Error(somefile.h:983): cannot understand prototype: 'multiline_example( \ '
      
      This patch fixes the issue by appending all lines ending in a blackslash
      (optionally followed by whitespace), removing the backslash and any
      whitespace after it prior to appending (just like the C pre-processor
      would).
      
      This fixes a break in kerel-doc introduced by the additions to rbtree.h.
      Signed-off-by: default avatarDaniel Santos <daniel.santos@pobox.com>
      Cc: Randy Dunlap <rdunlap@xenotime.net>
      Cc: Michal Marek <mmarek@suse.cz>
      Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
      Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
      65478428
  21. 31 Aug, 2012 1 commit
  22. 17 Aug, 2012 1 commit
  23. 23 Jan, 2012 1 commit
  24. 31 Mar, 2011 1 commit
  25. 06 Jan, 2011 1 commit
    • Randy Dunlap's avatar
      kernel-doc: code reorganization · 8484baaa
      Randy Dunlap authored
      Move 'main' code vs. subroutines around so that they are not so
      intermixed, for better readability/understanding (relative to Perl).
      It was messy to follow the primary flow of code execution with the
      code being mixed.  Now the code begins with data initialization,
      followed by all subroutines, then ends with the main code execution.
      
      This is almost totally source code movement, with a few changes as
      needed for forward declarations.
      Signed-off-by: default avatarRandy Dunlap <randy.dunlap@oracle.com>
      Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
      8484baaa
  26. 18 Nov, 2010 1 commit
    • Randy Dunlap's avatar
      kernel-doc: escape xml for structs · 2b35f4d9
      Randy Dunlap authored
      scripts/kernel-doc was leaving unescaped '<', '>', and '&' in
      generated xml output for structs.  This causes xml parser errors.
      Convert these characters to "&lt;", "&gt;", and "&amp;" as needed
      to prevent errors.
      
      Most of the conversion was already done; complete it just before
      output.
      
      Documentation/DocBook/device-drivers.xml:41883: parser error : StartTag: invalid element name
      #define INPUT_KEYMAP_BY_INDEX	(1 << 0)
      Signed-off-by: default avatarRandy Dunlap <randy.dunlap@oracle.com>
      Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
      2b35f4d9
  27. 11 Sep, 2010 2 commits
  28. 11 Aug, 2010 1 commit
    • Randy Dunlap's avatar
      mtd/nand_base: fix kernel-doc warnings & typos · b6d676db
      Randy Dunlap authored
      Fix mtd/nand_base.c kernel-doc warnings and typos.
      
      Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'mtd'
      Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'ofs'
      Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'len'
      Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'invert'
      Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'mtd'
      Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'ofs'
      Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'len'
      Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'mtd'
      Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'ofs'
      Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'len'
      Warning(drivers/mtd/nand/nand_base.c:2087): No description found for parameter 'len'
      Signed-off-by: default avatarRandy Dunlap <randy.dunlap@oracle.com>
      Cc: David Woodhouse <dwmw2@infradead.org>
      Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
      Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
      b6d676db
  29. 10 Aug, 2010 1 commit
    • Randy Dunlap's avatar
      mtd/nand_base: fix kernel-doc warnings & typos · db9ebb7c
      Randy Dunlap authored
      Fix mtd/nand_base.c kernel-doc warnings and typos.
      
      Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'mtd'
      Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'ofs'
      Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'len'
      Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'invert'
      Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'mtd'
      Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'ofs'
      Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'len'
      Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'mtd'
      Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'ofs'
      Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'len'
      Warning(drivers/mtd/nand/nand_base.c:2087): No description found for parameter 'len'
      Signed-off-by: default avatarRandy Dunlap <randy.dunlap@oracle.com>
      Signed-off-by: default avatarDavid Woodhouse <David.Woodhouse@intel.com>
      db9ebb7c
  30. 24 Mar, 2010 2 commits
  31. 12 Mar, 2010 1 commit
  32. 27 Feb, 2010 1 commit