linux.git/Documentation/doc-guide, branch v4.16-rc2

scripts: kernel-doc: parse next structs/unions

2017-12-21T20:41:46+00:00

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 
Signed-off-by: Jonathan Corbet

docs: kernel-doc.rst: add documentation about man pages

2017-12-21T20:41:46+00:00

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

docs: kernel-doc.rst: improve typedef documentation

2017-12-21T20:41:46+00:00

Add documentation about typedefs for function prototypes and
move it to happen earlier.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

docs: kernel-doc.rst: improve structs chapter

2017-12-21T20:41:46+00:00

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

docs: kernel-doc.rst: improve function documentation section

2017-12-21T20:41:46+00:00

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

docs: kernel-doc.rst: improve private members description

2017-12-21T20:41:45+00:00

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

docs: kernel-doc.rst: better describe kernel-doc arguments

2017-12-21T20:41:45+00:00

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

Documentation: fix ref to sphinx/kerneldoc.py

2017-10-19T18:57:10+00:00

Signed-off-by: Tom Saeger 
Signed-off-by: Jonathan Corbet

sphinx.rst: Allow Sphinx version 1.6 at the docs

2017-08-26T21:50:27+00:00

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

sphinx.rst: document scripts/sphinx-pre-install script

2017-07-23T21:51:45+00:00

Now that we have a script to check for Sphinx dependencies,
document it.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet