According to the old project site, https://sourceforge.net/projects/fuse/
the project has moved to https://github.com/libfuse/ so we update the
link to point to the latest libfuse release.
Signed-off-by: Martin Kepplinger <martink@posteo.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Andy Shevchenko [Mon, 26 Mar 2018 11:50:27 +0000 (14:50 +0300)]
dmaengine: Fix spelling for parenthesis in dmatest documentation
Fix spelling for parenthesis in dmatest documentation.
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
[ jc: did s/parenthesis/parentheses/ and reflowed ] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
COPYING: create a new file with points to the Kernel license files
With the addition of SPDX patchset, the contents of COPYING file
is now duplicated at two other files under LICENSE:
LICENSES/preferred/GPL-2.0
LICENSES/exceptions/Linux-syscall-note
It is easy to check that the contents of the licence written on
those files are identical with COPYING using:
Also, a new file was added, with describes how SPDX should work at
the Kernel source files:
Documentation/process/license-rules.rst
Instead fo having it copying the contents of two files, and not
even mentioning the third one, replace it by a file whose content
points to the other tree files, preserving the Kernel's license.
Adjust license-rules.rst accordingly.
Please notice that this file preserves the Kernel license as
is, without any changes.
Masanari Iida [Fri, 2 Mar 2018 13:30:13 +0000 (22:30 +0900)]
xfs: Change URL for the project in xfs.txt
The oss.sgi.com doesn't exist any more.
Change it to current project URL, https://xfs.wiki.kernel.org/
Signed-off-by: Masanari Iida <standby24x7@gmail.com> Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Aishwarya Pant [Fri, 23 Feb 2018 10:19:59 +0000 (15:49 +0530)]
block: rbd: update sysfs interface
The existing sysfs interface has been updated to be in the same format
as described in Documentation/ABI/README. This will be useful for
scripting and tracking changes in the ABI. Attributes have been grouped
by functionality and/or the date on which they were added.
There are a couple of more changes:
- The attributes have been annotated with file permissions RO/RW/WO.
- Added description of the bus attribute supported_features
Signed-off-by: Aishwarya Pant <aishpant@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
"This file" indeed was moved once, but at some point "this file", the
top-level README, becomes a file in itself. Now that time has come :)
Let's describe how things are, and suggest reading "this file" first,
"this file" simply being a the admin-guide README file, not a file that
was once moved.
Signed-off-by: Martin Kepplinger <martink@posteo.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Dave Hansen [Wed, 7 Mar 2018 21:46:24 +0000 (13:46 -0800)]
docs: clarify security-bugs disclosure policy
I think we need to soften the language a bit. It might scare folks
off, especially the:
We prefer to fully disclose the bug as soon as possible.
which is not really the case. Linus says:
It's not full disclosure, it's not coordinated disclosure,
and it's not "no disclosure". It's more like just "timely
open fixes".
I changed a bit of the wording in here, but mostly to remove the word
"disclosure" since it seems to mean very specific things to people
that we do not mean here.
Signed-off-by: Dave Hansen <dave.hansen@linux.intel.com> Reviewed-by: Dan Williams <dan.j.williams@intel.com> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Acked-by: Kees Cook <keescook@chromium.org> Cc: Thomas Gleixner <tglx@linutronix.de> Cc: Linus Torvalds <torvalds@linux-foundation.org> Cc: Alan Cox <gnomes@lxorguk.ukuu.org.uk> Cc: Andrea Arcangeli <aarcange@redhat.com> Cc: Andy Lutomirski <luto@kernel.org> Cc: Tim Chen <tim.c.chen@linux.intel.com> Cc: Alexander Viro <viro@zeniv.linux.org.uk> Cc: Andrew Morton <akpm@linux-foundation.org> Cc: Mark Rutland <mark.rutland@arm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Changbin Du [Sat, 17 Feb 2018 05:39:35 +0000 (13:39 +0800)]
trace doc: convert trace/ftrace-design.txt to rst format
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. This documentation is not synced with current
code, so mark it as out of date.
Cc: Steven Rostedt <rostedt@goodmis.org> Signed-off-by: Changbin Du <changbin.du@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
When Co-Developed-by tag was added, docs were only added to
Documention/process/5.Posting.rst and were not added to
Documention/process/submitting-patches.rst
Add documentation to Documention/process/submitting-patches.rst
Signed-off-by: Tobin C. Harding <me@tobin.cc>
[jc: tweaked commas in the subheading] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Matthew Wilcox [Fri, 2 Mar 2018 18:40:14 +0000 (10:40 -0800)]
Documentation/sphinx: Fix Directive import error
Sphinx 1.7 removed sphinx.util.compat.Directive so people
who have upgraded cannot build the documentation. Switch to
docutils.parsers.rst.Directive which has been available since
docutils 0.5 released in 2009.
Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694 Co-developed-by: Takashi Iwai <tiwai@suse.de> Acked-by: Jani Nikula <jani.nikula@intel.com> Cc: stable@vger.kernel.org Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Aishwarya Pant [Fri, 19 Jan 2018 12:31:47 +0000 (18:01 +0530)]
Documentation: rapidio: move sysfs interface to ABI
Right now, the description of the rapidio sysfs interfaces is in
Documentation/rapidio/sysfs.txt. Since these are a part of the ABI, they
should be in Documentation/ABI along with the rest.
Add documentation for core and hardware specific infiniband interfaces.
The descriptions have been collected from git commit logs, reading
through code and data sheets. Some drivers have incomplete doc and are
annotated with the comment '[to be documented]'.
Signed-off-by: Aishwarya Pant <aishpant@gmail.com> Reviewed-by: Hal Rosenstock <hal@mellanox.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Aishwarya Pant [Mon, 19 Feb 2018 18:16:53 +0000 (23:46 +0530)]
aoe: document sysfs interface
Documentation has been compiled from git commit logs and descriptions in
Documentation/aoe/aoe.txt. This should be useful for scripting and
tracking changes in the ABI.
Signed-off-by: Aishwarya Pant <aishpant@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Aishwarya Pant [Fri, 23 Feb 2018 13:16:32 +0000 (18:46 +0530)]
Documentation/ABI: clean up sysfs-class-pktcdvd
Clean up the sysfs documentation such that it is in the same format as
described in Documentation/ABI/README. Mainly, the patch moves the
attribute names to the 'What:' field. This might be useful for scripting
and tracking changes in the ABI.
Signed-off-by: Aishwarya Pant <aishpant@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mike Rapoport [Tue, 20 Feb 2018 18:36:25 +0000 (20:36 +0200)]
doc-guide: kernel-doc: add comment about formatting verification
Currently there is no automated checking for kernel-doc comments except
running 'kernel-doc -v -none <filename>'. Mention the possibility to run
kernel-doc to verify formatting of the comments in the kernel-doc guide.
Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Tue, 20 Feb 2018 19:29:50 +0000 (12:29 -0700)]
Merge branch 'kerneldoc2' into docs-next
So once upon a time I set out to fix the problem reported by Tobin wherein
a literal block within a kerneldoc comment would be corrupted in
processing. On the way, though, I got annoyed at the way I have to learn
how kernel-doc works from the beginning every time I tear into it.
As a result, seven of the following eight patches just get rid of some dead
code and reorganize the rest - mostly turning the 500-line process_file()
function into something a bit more rational. Sphinx output is unchanged
after these are applied. Then, at the end, there's a tweak to stop messing
with literal blocks.
If anybody was unaware that I've not done any serious Perl since the
1990's, they will certainly understand that fact now.
Jonathan Corbet [Tue, 20 Feb 2018 19:24:23 +0000 (12:24 -0700)]
docs: Add an SPDX header to kernel-doc
Add the SPDX header while I'm in the neighborhood. The source itself just
says "GNU General Public License", but it also refers people to the COPYING
file for further information. Since COPYING says 2.0-only, that is what I
have put into the header.
admin-guide: Fix list formatting in tained-kernels.html
Without this patch, the points 1-9 in the list are rendered as an HTML
blockquote containing a list, causing them to be indented further than
the rest of the list.
While at it, also fix the quotation marks around G and P.
Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
doc-guide: kernel-doc: fix example for nested_foobar struct
There's a missing */ at the end of Kernel docs example.
Even adding it, it will still produce 3 warnings:
example:33: warning: Function parameter or member 'bar' not described in 'nested_foobar'
example:33: warning: Function parameter or member 'bar.st1' not described in 'nested_foobar'
example:33: warning: Function parameter or member 'bar.st2' not described in 'nested_foobar'
So, make the example more complete and add the missing end
of comment there.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mike Rapoport [Tue, 13 Feb 2018 11:31:46 +0000 (13:31 +0200)]
scripts: kernel_doc: fixup reporting of function identifiers
When function description includes brackets after the function name as
suggested by Documentation/doc-guide/kernel-doc, the kernel-doc script
omits the function name from "Scanning doc for" report.
Extending match for identifier name with optional brackets fixes this
issue.
Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Tue, 6 Feb 2018 22:58:45 +0000 (15:58 -0700)]
docs: kernel-doc: Don't mangle literal code blocks in comments
It can be useful to put code snippets into kerneldoc comments; that can be
done with the "::" operator at the end of a line like this::
if (desperate)
run_in_circles();
The ".. code-block::" directive can also be used to this end. kernel-doc
currently fails to understand these literal blocks and applies its normal
markup to them, which is then treated as literal by sphinx. The result is
unsightly markup instead of a useful code snippet.
Apply a hack to the output code to recognize literal blocks and avoid
performing any special markup on them. It's ugly, but that means it fits
in well with the rest of the script.
Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Mon, 5 Feb 2018 23:11:47 +0000 (16:11 -0700)]
docs: kernel-doc: Finish moving STATE_* code out of process_file()
Move STATE_INLINE and STATE_DOCBLOCK code out of process_file(), which now
actually fits on a single screen. Delete an unused variable and add a
couple of comments while I'm at it.
Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Mon, 5 Feb 2018 20:56:45 +0000 (13:56 -0700)]
docs: kernel-doc: Rename and split STATE_FIELD
STATE_FIELD describes a parser state that can handle any part of a
kerneldoc comment body; rename it to STATE_BODY to reflect that.
The $in_purpose variable was a hidden substate of STATE_FIELD; get rid of
it and make a proper state (STATE_BODY_MAYBE) instead. This will make the
subsequent process_file() splitup easier.
Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Mon, 5 Feb 2018 19:40:15 +0000 (12:40 -0700)]
docs: kernel-doc: Get rid of xml_escape() and friends
XML escaping is a worry that came with DocBook, which we no longer have any
dealings with. So get rid of the useless xml_escape()/xml_unescape()
functions. No change to the generated output.
Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Matthew Wilcox [Tue, 13 Feb 2018 21:15:37 +0000 (13:15 -0800)]
Restructure kernel-doc.rst
I found the layout confusing with multiple introductions to what
kernel-doc is and how to use it.
I made the following changes:
- Moved the 'Including kernel-doc comments' section to the end of
the document -- we should explain what it *is* before we explain
how to integrate it.
- Moved the 'Recommendations' subsection to the top. We want people
to know what to document before telling them how to do it.
- Rewrite the 'Writing kernel-doc comments' section, integrating
the 'Recommendations' subsection and a paragraph from 'How to format
kernel-doc comments'.
- Remove the paragraph about the kernel-doc script; we're supposed to
be teaching people how to use punctuation to write pretty documentation,
not documenting the build tooling.
- Split the 'Parameters and member arguments' section into 'Function
parameters' and 'Members'. Structure members are not commonly
referred to as arguments.
- Integrate the 'private:' and 'public:' tag descriptions into the
'Members' section.
- Move the 'In-line member documentation comments' subsection up to be
with the 'Members' section.
Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>