Commit graph

39 commits

Author SHA1 Message Date
Mike Rapoport
f2e8603604 Documentation/sphinx: allow "functions" with no parameters
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 <rppt@linux.vnet.ibm.com>
Acked-by: Matthew Wilcox <willy@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-06-30 07:52:42 -06:00
Federico Vaga
f3821276f6 doc:sphinx: fix parse-header description
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 [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]

        Where <options> can be: --debug, --help or --man.

Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-06-26 09:07:57 -06:00
Federico Vaga
c1ec85ff40 doc:doc-guide: fix a typo and an error
Fix a typo in sphinx.rst and a minor error in parse-header.rst

Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-06-26 09:07:25 -06:00
Mauro Carvalho Chehab
3259081991 MAINTAINERS & files: Canonize the e-mails I use at files
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 <mchehab@s-opensource.com>
Signed-off-by: Brian Warner <brian.warner@samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2018-05-04 06:21:06 -04:00
Mike Rapoport
8fcce5803a 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>
2018-02-23 08:06:15 -07:00
Mauro Carvalho Chehab
dbcce2bfb7 doc-guide: kernel-doc: add examples about nested union/structs
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-18 16:55:10 -07:00
Mauro Carvalho Chehab
d2253a4557 doc-guide: kernel-doc: move in-line section to be after nested struct
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-18 16:54:56 -07:00
Mauro Carvalho Chehab
6e96788bd8 doc-guide: kernel-doc: fix example for inlined comments
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-18 16:54:44 -07:00
Mauro Carvalho Chehab
3651d452fd 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>
2018-02-18 16:54:34 -07:00
Matthew Wilcox
46347502b0 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>
2018-02-13 14:22:01 -07:00
Matthew Wilcox
9831e5548a Fix whitespace in example
Line up the second line in the way that the example purports to be
showing.

Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-13 14:21:57 -07:00
Matthew Wilcox
5b229fbec8 Add scripts/split-man.pl
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 <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-13 14:21:52 -07:00
Matthew Wilcox
dcb50d979e Minor fixes to kernel-doc.rst
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 <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-13 14:21:48 -07:00
Matthew Wilcox
da70b8c475 Add documentation for Context section
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 <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-13 14:21:40 -07:00
Mauro Carvalho Chehab
8ad7216316 scripts: kernel-doc: parse next structs/unions
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 clock

With 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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21 13:41:46 -07:00
Mauro Carvalho Chehab
93626d7a76 docs: kernel-doc.rst: add documentation about man pages
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21 13:41:46 -07:00
Mauro Carvalho Chehab
bdb76f9e30 docs: kernel-doc.rst: improve typedef documentation
Add documentation about typedefs for function prototypes and
move it to happen earlier.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21 13:41:46 -07:00
Mauro Carvalho Chehab
553aa3c12e docs: kernel-doc.rst: improve structs chapter
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21 13:41:46 -07:00
Mauro Carvalho Chehab
fc275bf3b9 docs: kernel-doc.rst: improve function documentation section
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21 13:41:46 -07:00
Mauro Carvalho Chehab
01f2c18073 docs: kernel-doc.rst: improve private members description
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21 13:41:45 -07:00
Mauro Carvalho Chehab
63ac85174a docs: kernel-doc.rst: better describe kernel-doc arguments
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21 13:41:45 -07:00
Tom Saeger
f66d9066c0 Documentation: fix ref to sphinx/kerneldoc.py
Signed-off-by: Tom Saeger <tom.saeger@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-10-19 12:57:10 -06:00
Mauro Carvalho Chehab
95a40b86c4 sphinx.rst: Allow Sphinx version 1.6 at the docs
Now that the PDF building issues with Sphinx 1.6 got fixed,
update the documentation and scripts accordingly.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-26 15:50:27 -06:00
Mauro Carvalho Chehab
868366aaac sphinx.rst: document scripts/sphinx-pre-install script
Now that we have a script to check for Sphinx dependencies,
document it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-23 15:51:45 -06:00
Mauro Carvalho Chehab
6e322a17fb sphinx.rst: better organize the documentation about PDF build
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-17 13:18:42 -06:00
Mauro Carvalho Chehab
d43e5ae974 sphinx.rst: describe the install requirements for kfigure
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-17 13:18:36 -06:00
Mauro Carvalho Chehab
29fd35bd02 sphinx.rst: fix unknown reference
There's no "Sphinx C Domain" reference at the Kernel
documentation. So, don't use references for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-17 13:18:30 -06:00
Mauro Carvalho Chehab
58ef4a42dd sphinx.rst: explain the usage of virtual environment
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-17 13:18:24 -06:00
Mauro Carvalho Chehab
b8b07b5c8d docs-rst: move Sphinx install instructions to sphinx.rst
The toolchain used by Sphinx is somewhat complex, and installing
it should be part of the doc-guide.

Move it out of changes.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-17 13:18:18 -06:00
Mauro Carvalho Chehab
5d47c31b59 kernel-doc: describe the `literal` syntax
changeset b97f193abf ("scripts/kernel-doc: fix parser
for apostrophes") added support for ``literal`` inside
kernel-doc, in order to allow using the "%" symbol inside
a literal block, as this is used at printk() description.

Document it.

Fixes: b97f193abf ("scripts/kernel-doc: fix parser for apostrophes")
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16 08:44:24 -03:00
Mauro Carvalho Chehab
ff41c41943 docs: update old references for DocBook from the documentation
DocBook is mentioned several times at the documentation. Update
the obsolete references from it at the DocBook.

Acked-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16 08:44:19 -03:00
Mauro Carvalho Chehab
cb43fb5775 docs: remove DocBook from the building system
Now that we don't have any DocBook anymore, remove it from
the building system.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16 08:44:19 -03:00
Markus Heiser
db6ccf23e8 docs-rst: automatically convert Graphviz and SVG images
This patch brings scalable figure, image handling and a concept to
embed *render* markups:

* DOT (http://www.graphviz.org)
* SVG

For image handling use the 'image' replacement::

    .. kernel-image::  svg_image.svg
       :alt:    simple SVG image

For figure handling use the 'figure' replacement::

    .. kernel-figure::  svg_image.svg
       :alt:    simple SVG image

       SVG image example

Embed *render* markups (or languages) like Graphviz's **DOT** is
provided by the *render* directive.::

  .. kernel-render:: DOT
     :alt: foobar digraph
     :caption: Embedded **DOT** (Graphviz) code.

     digraph foo {
      "bar" -> "baz";
     }

The *render* directive is a concept to integrate *render* markups and
languages, yet supported markups:

* DOT: render embedded Graphviz's **DOT**
* SVG: render embedded Scalable Vector Graphics (**SVG**)

Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Tested-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> (v2 - v5)
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> (v1, v6)
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-03-09 02:59:26 -07:00
Daniel Vetter
c3c53600f6 doc: Explain light-handed markup preference a bit better
We're still pretty far away from anything like a consensus, but
there's clearly a lot of people who prefer an as-light as possible
approach to converting existing .txt files to .rst. Make sure this is
properly taken into account and clear.

Motivated by discussions with Peter and Christoph and others.

Cc: Christoph Hellwig <hch@infradead.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-03-09 02:44:44 -07:00
Mauro Carvalho Chehab
c339665666 docs-rst: parse-headers.pl: cleanup the documentation
Keeping both rst and in-file documentation in sync can be harsh.

So, simplify the script's internal documntation to a bare minimum,
and add a mention to the ReST file with its full documentation.

This way, a quick help is still available at the command line,
while the complete one is maintained at the ReST format.

As we won't be using pad2rst anymore, do a cleanup at the ReST
file.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:08:09 -07:00
Jonathan Corbet
ca9667fcc8 Merge branch 'mauro-doc' into docs-next 2016-11-19 10:28:58 -07:00
Mauro Carvalho Chehab
2dde123b23 parse-headers.rst: add an introduction to the man page
The pod2rst tool generated a man page for parse-headers.pl
script, but it is better to put it into some context.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19 10:22:15 -07:00
Mauro Carvalho Chehab
327f5a754a parse-headers.pl: add documentation for this script
Provide a man page for parse-headers.pl, describing
how to use it.

The documentation on ReST format was generated via pod2rst:
	http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19 10:22:08 -07:00
Mauro Carvalho Chehab
1dc4bbf0b2 docs-rst: doc-guide: split the kernel-documentation.rst contents
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19 10:22:04 -07:00