Commit 7e5b7d1b authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

Merge branch 'docs-next' of git://git.lwn.net/linux into topic/docs-next 

* 'docs-next' of git://git.lwn.net/linux:
  doc-rst: kernel-doc: fix handling of address_space tags
  Revert "doc/sphinx: Enable keep_warnings"
  doc-rst: kernel-doc directive, fix state machine reporter
  docs: deprecate kernel-doc-nano-HOWTO.txt
  doc/sphinx: Enable keep_warnings
  Documentation: add watermark_scale_factor to the list of vm systcl file
  kernel-doc: Fix up warning output
  docs: Get rid of some kernel-documentation warnings
parents e5208ed2 a88b1672

Documentation/00-INDEX

+2 −2
Original line number Diff line number Diff line
@@ -255,10 +255,10 @@ kbuild/ 
	- directory with info about the kernel build process.

kdump/

	- directory with mini HowTo on getting the crash dump code to work.

kernel-doc-nano-HOWTO.txt

	- mini HowTo on generation and location of kernel documentation files.

kernel-docs.txt

	- listing of various WWW + books that document kernel internals.

kernel-documentation.rst

	- how to write and format reStructuredText kernel documentation

kernel-parameters.txt

	- summary listing of command line / boot prompt args for the kernel.

kernel-per-CPU-kthreads.txt

Documentation/CodingStyle

+1 −1
Original line number Diff line number Diff line
@@ -458,7 +458,7 @@ of the function, telling people what it does, and possibly WHY it does 
it.



When commenting the kernel API functions, please use the kernel-doc format.

See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc

See the files Documentation/kernel-documentation.rst and scripts/kernel-doc

for details.



Linux style for comments is the C89 "/* ... */" style.

Documentation/development-process/4.Coding

+1 −1
Original line number Diff line number Diff line
@@ -346,7 +346,7 @@ which have not been so documented, there is no harm in adding kerneldoc 
comments for the future; indeed, this can be a useful activity for

beginning kernel developers.  The format of these comments, along with some

information on how to create kerneldoc templates can be found in the file

Documentation/kernel-doc-nano-HOWTO.txt.

Documentation/kernel-documentation.rst.



Anybody who reads through a significant amount of existing kernel code will

note that, often, comments are most notable by their absence.  Once again,

Documentation/kernel-doc-nano-HOWTO.txt

+3 −0
Original line number Diff line number Diff line 
NOTE: this document is outdated and will eventually be removed.  See

Documentation/kernel-documentation.rst for current information.



kernel-doc nano-HOWTO

=====================

Documentation/kernel-documentation.rst

+6 −0
Original line number Diff line number Diff line
@@ -366,6 +366,8 @@ Domain`_ references. 
Cross-referencing from reStructuredText

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



.. highlight:: none



To cross-reference the functions and types defined in the kernel-doc comments

from reStructuredText documents, please use the `Sphinx C Domain`_

references. For example::
@@ -388,6 +390,8 @@ For further details, please refer to the `Sphinx C Domain`_ documentation. 
Function documentation

----------------------



.. highlight:: c



The general format of a function and function-like macro kernel-doc comment is::



  /**
@@ -568,6 +572,8 @@ DocBook XML [DEPRECATED] 
Converting DocBook to Sphinx

----------------------------



.. highlight:: none



Over time, we expect all of the documents under ``Documentation/DocBook`` to be

converted to Sphinx and reStructuredText. For most DocBook XML documents, a good

enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,

CRA Git | Maintained and supported by SUSTech CRA and CCSE