At some stage of the conversion pipeline, something thought that the
DocBook entity # should be rendered as NUM instead of #.
Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Currently msg_zerocopy is not included in any toctree. Sphinx emits a
build warning to this effect. The other three rst files in
Documentation/networking are all indexed. We can add msg_zerocopy to the
toctree to enable navigation of the document via HTML kernel docs.

Add msg_zerocopy to the networking/ toctree.
Signed-off-by: Tobin C. Harding <me@tobin.cc>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

This patch updates the documentation with the observations that led
to commit bdcf0a42 ("kernel: make groups_sort calling a
responsibility group_info allocators") and the new behaviour required.
Specifically that groups_sort() should be called on a new group_list
before set_groups() or set_current_groups() is called.
Signed-off-by: NeilBrown <neilb@suse.com>
[jc: use proper :c:func: references]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add the full text of the Mozilla Public License 1.1 to the kernel tree.  It was
copied directly from:

       https://spdx.org/licenses/MPL-1.1.html#licenseTextSigned-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add the full text of the GPL 1.0 license to the kernel tree.  It was
copied directly from:

       https://spdx.org/licenses/GPL-1.0.html#licenseTextSigned-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Copied from the Linux kernel COPYING file.

Add the required tags for reference and tooling.
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add the full text of the MIT license to the kernel tree.  It was copied
directly from:

  https://spdx.org/licenses/MIT.html#licenseText

Add the required tags for reference and tooling.
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add the full text of the BSD 3-clause "Clear" License to the
kernel tree.  It was copied directly from:

  https://spdx.org/licenses/BSD-3-Clause-Clear.html

Add the required tags for reference and tooling.
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add the full text of the BSD 3-clause "New" or "Revised" License to the
kernel tree.  It was copied directly from:

  https://spdx.org/licenses/BSD-3-Clause.html#licenseText

Add the required tags for reference and tooling.
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add the full text of the BSD 2-clause "Simplified" license to the kernel
tree.  It was copied directly from:

   https://spdx.org/licenses/BSD-2-Clause.html#licenseText

Add the required tags for reference and tooling.
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add the full text of the LGPL 2.1 license to the kernel tree.  It was
copied directly from:

   https://spdx.org/licenses/LGPL-2.1.html#licenseText

Add the required tags for reference and tooling.
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add the full text of the LGPL 2.0 license to the kernel tree.  It was
copied directly from:

   https://spdx.org/licenses/LGPL-2.0.html#licenseText

Add the required tags for reference and tooling.
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add the full text of the GPL 2.0 license to the LICENSES directory.  It was
copied directly from the COPYING file in the kernel source tree as it
differs from the public available version of the license in various places
including the FSF.

Philippe did some research on the GPL2.0 history:

  There is NO trustworthy version of an official GPL 2.0 text: the FSF
  official texts are all fubar (if only in small and subtle ways). The FSF
  texts should be authoritative, but then which one? They published more
  GPL 2.0 versions than most. So we would be hard pressed to blame SPDX or
  the OSI for having their own minor variant.

  Then in digging further, I found the ONE true original GPL with a file
  time stamp on June 2 1991, 01:50 (AM?, PM? unknown time zone?)  ! in an
  old GCC archive.

  For the posterity and everyone's enjoyment I have built a git history
  of GPL 2.0 Mark1 to Mark6

  See https://github.com/pombredanne/gpl-history/commits/master/COPYING

  I also added a shorter history of the Linux COPYING text. The first
  version in Linus's git tree is based on the very fine and well tuned GPL
  2 Mark4, the first fully Y2K compliant version of the GPL 2, as you can
  see from the diffs with the former Mark3: that was dangerously stuck in
  the last century.

  The current version in is based on a rare GPL 2.0 Mark5.1 aka "Franklin
  St", that I do not have in my history yet and spells "Franklin St."
  rather than "Franklin Street."  Therefore there is likely another GPL 2.0
  version between Mark4 and Mark5 that I have yet to find and may not have
  been caught by the archive.org spiders. Here help and patches welcomed:
  this is likely an important missing link.

  Further information about this archaelogical research;

  http://lkml.kernel.org/r/CAOFm3uEzRMf261+O-Nm+9HDoEn9RbFjH=5J9i1C2GgMUg2G4LA@mail.gmail.com

Add the required tags for reference and tooling.
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Jonas Oberg <jonas@fsfe.org>
Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add a file to the Documentation directory to describe how file licenses
should be described in all kernel files, using the SPDX identifier, as well
as where all licenses should be in the kernel source tree for people to
refer to (LICENSES/).

Thanks to Kate and Greg for review and editing and Jonas for the
suggestions concerning the meta tags in the licenses files.
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Jonas Oberg <jonas@fsfe.org>
Reviewed-by: Jonathan Corbet <corbet@lwn.net>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The logic with inhibits warnings for definitions that is not
output is incomplete: it doesn't cover the cases where
OUTPUT_INTERNAL and OUTPUT_EXPORTED are used.

As the most common case is OUTPUT_ALL, place it first,
in order to optimize a litte bit the check logic.

Fixes: 2defb272 ("scripts: kernel-doc: apply filtering rules to warnings")
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Acked-and-Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

This link is replicated in most filesystems' config stanzas.  Referring
to an archived version of that site is pointless as it mostly deals with
patches; user documentation is available elsewhere.
Signed-off-by: Adam Borowski <kilobyte@angband.pl>
CC: Alexander Viro <viro@zeniv.linux.org.uk>
Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com>
Acked-by: Jan Kara <jack@suse.cz>
Acked-by: Dave Kleikamp <dave.kleikamp@oracle.com>
Acked-by: David Sterba <dsterba@suse.com>
Acked-by: "Yan, Zheng" <zyan@redhat.com>
Acked-by: Chao Yu <yuchao0@huawei.com>
Acked-by: Jaegeuk Kim <jaegeuk@kernel.org>
Acked-by: Steve French <smfrench@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

drivers/md/faulty.c has been renamed to md-faulty.c after
following commit merged int to the main line.

  935fe098 .

But the file name in fault-injection.txt has not been changed.
Now the actual file name and document are in sync.
Signed-off-by: Masanari Iida <standby24x7@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

 - Move errseq.rst into core-api
 - Add errseq to the core-api index
 - Promote the header to a more prominent header type, otherwise we get three
   entries in the table of contents.
 - Reformat the table to look nicer and be a little more proportional in
   terms of horizontal width per bit (the SF bit is still disproportionately
   large, but there's no way to fix that).
 - Include errseq kernel-doc in the errseq.rst
 - Neaten some kernel-doc markup
Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Reviewed-by: Jeff Layton <jlayton@redhat.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Now that kernel-doc can hanle nested structs/unions, describe
such fields at w1_netlink_message_types.
Acked-by: Evgeniy Polyakov <zbr@ioremap.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

kernel-doc-nano-HOWTO.txt has a chapter about man pages
production. While we don't have a working  "make manpages"
target, add it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add documentation about typedefs for function prototypes and
move it to happen earlier.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

There is a mess on this chapter: it suggests that even
enums and unions should be documented with "struct". That's
not the way it should be ;-)

Fix it and move it to happen earlier.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Move its contents to happen earlier and improve the description
of return values, adding a subsection to it. Most of the contents
there came from kernel-doc-nano-HOWTO.txt.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The private members section can now be moved to be together
with the arguments section. Move it there and add an example
about the usage of public:
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Add a new section to describe kernel-doc arguments,
adding examples about how identation should happen, as failing
to do that causes Sphinx to do the wrong thing.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

add missing indent whitespace to list item, fixes the warning:

- process/submit-checklist.rst:41: WARNING: Enumerated list ends without a blank
  line; unexpected unindent.
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Reviewed-by: Darren Hart (VMware) <dvhart@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ftrace-uses.rst is not yet included into any toctree, but since it is
a .rst file, it is parsed by the Sphinx build. Thats, why we see some
WARNINGS:

- trace/ftrace-uses.rst:53: WARNING: Definition list ends without a blank line; unexpected unindent.
- trace/ftrace-uses.rst:89: WARNING: Inline emphasis start-string without end-string.
- trace/ftrace-uses.rst:89: WARNING: Inline emphasis start-string without end-strin

Fixing the code-block directives results in a less noisy build, but the 'not
included' WARNING will be stay:

- trace/ftrace-uses.rst: WARNING: document isn't included in any toctree
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Acked-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

A reference to printk-formats.txt didn't get updated when the file moved;
fix that.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

`Documentation/i2c/dev-interface` gives examples for accessing i2c from
userspace.

There's a note that warns developers about the two `i2c-dev.h` header
files which were shipped with the kernel and i2c-tools separately.

However, following i2c-tools commits suggest that the header files are now
identical (in functionality) and `i2c_*` helper functions are now defined
in a separate header called `i2c/smbus.h`, which is distributed with
i2c-tools:

commit 652619121974 ("Minimize differences with kernel flavor")
commit 93caf007f4cb ("Move SMBus helper functions to include/i2c/smbus.h")

Thus, I've converted the warning paragraph into a historical note and
updated the suggested header files.
Signed-off-by: Cengiz Can <cengizc@gmail.com>
Cc: Wolfram Sang <wsa@the-dreams.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>