linux-toradex.git/Documentation/kernel-doc-nano-HOWTO.txt, branch v4.1.25

kernel-doc: Update references to SGML to refs to XML instead.

2013-05-28T10:02:11+00:00

Since the "sgmldocs" target is simply a pointer to the newer "xmldocs"
target, update the documentation to reflect this.

Signed-off-by: Robert P. J. Day 
Signed-off-by: Jiri Kosina

Kernel-doc: Convention: Use a "Return" section to describe return values

2012-11-27T20:08:57+00:00

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: Yacine Belkadi 
Signed-off-by: Rob Landley 
Signed-off-by: Jiri Kosina

docbook: warn on unused doc entries

2010-09-11T23:49:21+00:00

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: Johannes Berg 
Signed-off-by: Randy Dunlap 
Signed-off-by: Linus Torvalds

documentation: update kernel-doc-nano-HOWTO information

2010-01-11T17:34:07+00:00

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: Randy Dunlap 
Signed-off-by: Andrew Morton 
Signed-off-by: Linus Torvalds

kernel-doc: allow multi-line declaration purpose descriptions

2009-09-18T16:48:52+00:00

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: Johannes Weiner 
Signed-off-by: Randy Dunlap 
Signed-off-by: Linus Torvalds

kernel-doc: restrict syntax for private: and public:

2009-05-02T22:36:10+00:00

scripts/kernel-doc can (incorrectly) delete struct members that are
surrounded by /* ...  */  /* ...  */ 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: Randy Dunlap 
Signed-off-by: Andrew Morton 
Signed-off-by: Linus Torvalds

kernel-doc: preferred ending marker and examples

2009-02-11T22:25:36+00:00

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: Randy Dunlap 
Reported-by: Robert Love 
Signed-off-by: Andrew Morton 
Signed-off-by: Linus Torvalds

documentation: how to use DOC: section blocks

2009-01-06T23:59:28+00:00

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: Randy Dunlap 
Cc: Johannes Berg 
Signed-off-by: Andrew Morton 
Signed-off-by: Linus Torvalds

docs: document how to write @varargs in kernel-doc

2009-01-06T23:59:28+00:00

Add documentation on how to use kernel-doc for function parameters
that are "..." (varargs).

Signed-off-by: Randy Dunlap 
Cc: Rusty Russell 
Signed-off-by: Andrew Morton 
Signed-off-by: Linus Torvalds

sched: add kernel doc for the completion, fix kernel-doc-nano-HOWTO.txt

2008-08-26T08:26:54+00:00

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: Kevin Diggs 
Signed-off-by: Ingo Molnar