DocBook is mentioned several times at the documentation. Update
the obsolete references from it at the DocBook.
Acked-by: NSeongJae Park <sj38.park@gmail.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Having the kernel-documentation at the topmost level doesn't
allow generating a separate PDF file for it. Also, makes harder
to add extra contents. So, place it on a sub-dir.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Now that the new Sphinx world order is taking over, the information in
kernel-doc-nano-HOWTO.txt is outmoded.  I hate to remove it altogether,
since it's one of those files that people expect to find.  But we can add a
warning and fix all the other pointers to it.
Reminded-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

docproc.c was moved in 2011 from scripts/basic to scripts
-> updated the references accordingly
Signed-off-by: NPeter Huewe <peterhuewe@gmx.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Since the "sgmldocs" target is simply a pointer to the newer "xmldocs"
target, update the documentation to reflect this.
Signed-off-by: NRobert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: NJiri Kosina <jkosina@suse.cz>

Non-void functions should describe their return values in their kernel-doc
comments. Currently, some don't, others do in various forms. For example:
   * Return the result.
   * Return: The result.
   * Returns the result.
   * Returns: the result.
   * Return Value: The result.
   * @return: the result.
   * This function returns the result.
   * It will return the result.

Defining a convention would improve consistency of kernel-doc comments. It
would also help scripts/kernel-doc identify the text describing the return
value of a function. Thus allowing additional checks on the comments, and
suitable highlighting in the generated docs (man pages, html, etc).

So, as a convention, use a section named "Return" to describe the return
value of a function.
Signed-off-by: NYacine Belkadi <yacine.belkadi.1@gmail.com>
Acked-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NMichal Marek <mmarek@suse.cz>

Non-void functions should describe their return values in their kernel-doc
comments. Currently, some don't, others do in various forms. For example:
   * Return the result.
   * Return: The result.
   * Returns the result.
   * Returns: the result.
   * Return Value: The result.
   * @return: the result.
   * This function returns the result.
   * It will return the result.

Defining a convention would improve consistency of kernel-doc comments. It
would also help scripts/kernel-doc identify the text describing the return
value of a function. Thus allowing additional checks on the comments, and
suitable highlighting in the generated docs (man pages, html, etc).

So, as a convention, use a section named "Return" to describe the return
value of a function.
Signed-off-by: NYacine Belkadi <yacine.belkadi.1@gmail.com>
Signed-off-by: NRob Landley <rob@landley.net>
Signed-off-by: NJiri Kosina <jkosina@suse.cz>

When you don't use !E or !I but only !F, then it's very easy to miss
including some functions, structs etc.  in documentation.  To help
finding which ones were missed, allow printing out the unused ones as
warnings.

For example, using this on mac80211 yields a lot of warnings like this:

  Warning: didn't use docs for DOC: mac80211 workqueue
  Warning: didn't use docs for ieee80211_max_queues
  Warning: didn't use docs for ieee80211_bss_change
  Warning: didn't use docs for ieee80211_bss_conf

when generating the documentation for it.
Signed-off-by: NJohannes Berg <johannes.berg@intel.com>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Remove comments about function short descriptions not allowed to be on
multiple lines (that was fixed/changed recently).

Add comments that function "section header:" names need to be unique per
function/struct/union/typedef/enum.
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Allow the short description after symbol name and dash in a kernel-doc
comment to span multiple lines, e.g. like this:

	/**
	 * unmap_mapping_range - unmap the portion of all mmaps in the
	 *	specified address_space corresponding to the specified
	 *	page range in the underlying file.
	 * @mapping: the address space containing mmaps to be unmapped.
	 * ...
	 */

The short description ends with a parameter description, an empty line
or the end of the comment block.
Signed-off-by: NJohannes Weiner <hannes@cmpxchg.org>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

scripts/kernel-doc can (incorrectly) delete struct members that are
surrounded by /* ...  */ <struct members> /* ...  */ if there is a /*
private: */ comment in there somewhere also.

Fix that by making the "/* private:" only allow whitespace between /* and
"private:", not anything/everything in the world.

This fixes some erroneous kernel-doc warnings that popped up while
processing include/linux/usb/composite.h.
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Fix kernel-doc-nano-HOWTO.txt to use */ as the ending marker in kernel-doc
examples and state that */ is the preferred ending marker.
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Reported-by: NRobert Love <robert.w.love@intel.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Add info on how to use DOC: sections in kernel-doc.  DOC: sections enable
the addition of inline source file comments that are general in nature
instead of being specific to a function, struct, union, enum, or typedef.
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Cc: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Add documentation on how to use kernel-doc for function parameters
that are "..." (varargs).
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Cc: Rusty Russell <rusty@rustcorp.com.au>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

This patch adds kernel doc for the completion feature.

An error in the split-man.pl PERL snippet in kernel-doc-nano-HOWTO.txt is
also fixed.
Signed-off-by: NKevin Diggs <kevdig@hypersurf.com>
Signed-off-by: NIngo Molnar <mingo@elte.hu>

Provide documentation of the kernel-doc documentation conventions oriented
to kernel hackers.

Since I figure that there will be more people reading this
kernel-doc-nano-HOWTO.txt file who are kernel developers focused on the
rest of the kernel, than there will be readers of this file who are
documentation developers extracting that embedded kernel-doc
documentation, I have taken the liberty of making the new section added
here:

  How to format kernel-doc comments

the first section of the kernel-doc-nano-HOWTO.txt file.

This first section is intended to introduce, motivate and provide basic
usage of the kernel-doc mechanism for kernel hackers developing other
portions of the kernel.
Signed-off-by: NPaul Jackson <pj@sgi.com>
Acked-by: NRandy Dunlap <rdunlap@xenotime.net>
Cc: Alan Cox <alan@lxorguk.ukuu.org.uk>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Explain a couple of the most common errors in kernel-doc usage.
Signed-off-by: NRobert P. J. Day <rpjday@mindspring.com>
Acked-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

In kernel-doc syntax, be a little flexible:  allow whitespace between
a function parameter name and the colon that must follow it, such as:
	@pdev : PCI device to unplug

(This allows lots of megaraid kernel-doc to work without tons of
editing.)
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Correct a few comments in kernel-doc Doc and source files.

(akpm: note: the patch removes a non-ascii character and might have to be
applied by hand..)
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@osdl.org>
Signed-off-by: NLinus Torvalds <torvalds@osdl.org>

- Add info that structs, unions, enums, and typedefs are supported.

- Add doc about "private:" and "public:" tags for struct fields.

- Fix some typos.

- Remove some trailing whitespace.
Signed-off-by: NRandy Dunlap <rdunlap@xenotime.net>
Signed-off-by: NAndrew Morton <akpm@osdl.org>
Signed-off-by: NLinus Torvalds <torvalds@osdl.org>

Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.

Let it rip!