17 Jul, 2019
1 commit
-
Now that the latex_documents are handled automatically, we can
remove those extra conf.py files.Signed-off-by: Mauro Carvalho Chehab
28 Jun, 2019
1 commit
-
fix the disjunction by replacing "of" with "or".
Signed-off-by: Sheriff Esseson
Signed-off-by: Jonathan Corbet
27 Jun, 2019
1 commit
-
Now that we can mark up function() automatically, there is no reason to use
:c:func: and every reason to avoid it. Adjust the documentation to reflect
that fact.Signed-off-by: Jonathan Corbet
15 Jun, 2019
1 commit
-
There's a paragraph that explains how to create fixed width text block,
but it doesn't explains how to create fixed width text inline, although
this feature is really used through the documentation. Fix that adding a
quick note about it.Signed-off-by: André Almeida
Signed-off-by: Jonathan Corbet
31 May, 2019
1 commit
-
As discussed at the linux-doc ML, while we'll still support
version 1.3, it is time to recommend a more modern version.So, let's switch the minimal requirements to Sphinx 1.7.9,
as it has the "-jauto" flag, with makes a lot faster when
building documentation.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
20 Apr, 2019
1 commit
-
On almost all places, we're including ReST files without the
extension.Let's remove the extension here as well, in order to use just
one standard.Suggested-by: Jani Nikula
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
18 Feb, 2019
1 commit
-
"If no *function* if specified" should instead be
"If no *function* is specified".Reported-by: Matthew Wilcox
Signed-off-by: Frank Rowand
Signed-off-by: Jonathan Corbet
02 Feb, 2019
2 commits
-
Fix a typo in kernel-doc.rst
Signed-off-by: Frank Rowand
Signed-off-by: Jonathan Corbet -
(1) The command to generate man pages is truncated in the pdf version
of the document. Reformat the command into multiple lines to prevent
the truncation.(2) Older versions of git do not support all variants of pathspec
syntax. Provide commands to generate man pages for various
alternate syntax.Signed-off-by: Frank Rowand
Signed-off-by: Jonathan Corbet
15 Jan, 2019
1 commit
-
While using this guide to learn the new documentation method, I saw
a few phrases that I felt could be improved. These small changes
improve the grammar and choice of words to further enhance the
installation instructions.Signed-off-by: Joel Nider
Acked-by: Mike Rapoport
Acked-by: Matthew Wilcox
Signed-off-by: Jonathan Corbet
07 Dec, 2018
1 commit
-
Some documents are refering to others without links. With this
patch I add those missing links.This patch affects only documents under process/ and labels where
necessary.Signed-off-by: Federico Vaga
Signed-off-by: Jonathan Corbet
08 Nov, 2018
1 commit
-
In the Function documentation Section of kernel-doc.rst
there is a function_name() function as an example for
how to make a comment about a function.But at the end of that example there is a reference to foobar
instead of function_name.I think that should rather be function_name, because that
was the placeholder the whole example was using.Signed-off-by: Joris Gutjahr
Signed-off-by: Jonathan Corbet
30 Jun, 2018
1 commit
-
When kernel-doc:: specified in .rst document without explicit directives,
it outputs both comment and DOC: sections. If a DOC: section was explicitly
included in the same document it will be duplicated. For example, the
output generated for Documentation/core-api/idr.rst [1] has "IDA
description" in the "IDA usage" section and in the middle of the API
reference.This patch enables using "functions" directive without parameters to output
all the documentation excluding DOC: sections.[1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html
Signed-off-by: Mike Rapoport
Acked-by: Matthew Wilcox
Signed-off-by: Jonathan Corbet
26 Jun, 2018
2 commits
-
The description speaks about the option ``--man`` but it
does not exist. Instead, there is the option ``--usage``$ ./Documentation/sphinx/parse-headers.pl --man
Unknown option: man
Usage:
parse_headers.pl [] []Where can be: --debug, --help or --man.
Signed-off-by: Federico Vaga
Signed-off-by: Jonathan Corbet -
Fix a typo in sphinx.rst and a minor error in parse-header.rst
Signed-off-by: Federico Vaga
Signed-off-by: Jonathan Corbet
04 May, 2018
1 commit
-
From now on, I'll start using my @kernel.org as my development e-mail.
As such, let's remove the entries that point to the old
mchehab@s-opensource.com at MAINTAINERS file.For the files written with a copyright with mchehab@s-opensource,
let's keep Samsung on their names, using mchehab+samsung@kernel.org,
in order to keep pointing to my employer, with sponsors the work.For the files written before I join Samsung (on July, 4 2013),
let's just use mchehab@kernel.org.For bug reports, we can simply point to just kernel.org, as
this will reach my mchehab+samsung inbox anyway.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Brian Warner
Signed-off-by: Mauro Carvalho Chehab
23 Feb, 2018
1 commit
-
Currently there is no automated checking for kernel-doc comments except
running 'kernel-doc -v -none '. Mention the possibility to run
kernel-doc to verify formatting of the comments in the kernel-doc guide.Signed-off-by: Mike Rapoport
Signed-off-by: Jonathan Corbet
19 Feb, 2018
4 commits
-
It helps to give some examples about how to use in-line
comments also when nested union/structs are present. So add it.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
We want to give some examples about how to do in-line comments
for nested structs. So, move it to be after nested structs/unions
chapter.The section content was not changed on this patch.
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Without ending with a ";", kernel-doc doesn't recognize it
as an struct, and it fails to parse the example.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet
14 Feb, 2018
5 commits
-
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
Signed-off-by: Jonathan Corbet -
Line up the second line in the way that the example purports to be
showing.Signed-off-by: Matthew Wilcox
Signed-off-by: Jonathan Corbet -
Instead of asking the user to copy and paste a small perl script from
the documentation, just distribute the perl script in the scripts
directory.Signed-off-by: Matthew Wilcox
Signed-off-by: Jonathan Corbet -
The author clearly meant to use the word 'which' here. Also replace
some tabs with spaces which fixes the syntax highlighting in my editor.Signed-off-by: Matthew Wilcox
Signed-off-by: Jonathan Corbet -
This section is mentioned in scripts/kernel-doc, so we should mention it
in doc-guide/kernel-doc.rst. There are close to 500 comments using the
Context section already, and almost 300 using a Locking section which
fulfills much the same purpose (and should probably be converted for
consistency).Signed-off-by: Matthew Wilcox
Signed-off-by: Jonathan Corbet
22 Dec, 2017
7 commits
-
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 clockWith 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
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet -
Add documentation about typedefs for function prototypes and
move it to happen earlier.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet
20 Oct, 2017
1 commit
-
Signed-off-by: Tom Saeger
Signed-off-by: Jonathan Corbet
27 Aug, 2017
1 commit
-
Now that the PDF building issues with Sphinx 1.6 got fixed,
update the documentation and scripts accordingly.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
24 Jul, 2017
1 commit
-
Now that we have a script to check for Sphinx dependencies,
document it.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
18 Jul, 2017
4 commits
-
Instead of having it on just one note, add a separate section.
This way, we could later improve it, providing a better
guide about the needed steps for PDF builds.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
As we now have a document describing the install
requirements for Sphinx, add there the need for GraphViz
and ImageMagick.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
There's no "Sphinx C Domain" reference at the Kernel
documentation. So, don't use references for it.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
As the Sphinx build seems very fragile, specially for
PDF output, add a notice about how to use it on a virtual
environment.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet