Eric Lee / smarc-fsl-linux-kernel

30 Jun, 2018

1 commit

  • f2e860360   Documentation/sphinx: allow "functions" with no parameters ... Browse Code »

    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

    Mike Rapoport
     

26 Jun, 2018

2 commits

04 May, 2018

1 commit

  • 325908199   MAINTAINERS & files: Canonize the e-mails I use at files ... Browse Code »

    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

    Mauro Carvalho Chehab
     

23 Feb, 2018

1 commit

19 Feb, 2018

4 commits

14 Feb, 2018

5 commits

  • 46347502b   Restructure kernel-doc.rst ... Browse Code »

    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

    Matthew Wilcox
     
  • 9831e5548   Fix whitespace in example ... Browse Code »

    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

    Matthew Wilcox
     
  • 5b229fbec   Add scripts/split-man.pl ... Browse Code »

    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

    Matthew Wilcox
     
  • dcb50d979   Minor fixes to kernel-doc.rst ... Browse Code »

    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

    Matthew Wilcox
     
  • da70b8c47   Add documentation for Context section ... Browse Code »

    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

    Matthew Wilcox
     

22 Dec, 2017

7 commits

  • 8ad721631   scripts: kernel-doc: parse next structs/unions ... Browse Code »

    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

    Mauro Carvalho Chehab
     
  • 93626d7a7   docs: kernel-doc.rst: add documentation about man pages ... Browse Code »

    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

    Mauro Carvalho Chehab
     
  • bdb76f9e3   docs: kernel-doc.rst: improve typedef documentation ... Browse Code »

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

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

    Mauro Carvalho Chehab
     
  • 553aa3c12   docs: kernel-doc.rst: improve structs chapter ... Browse Code »

    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

    Mauro Carvalho Chehab
     
  • fc275bf3b   docs: kernel-doc.rst: improve function documentation section ... Browse Code »

    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

    Mauro Carvalho Chehab
     
  • 01f2c1807   docs: kernel-doc.rst: improve private members description ... Browse Code »

    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

    Mauro Carvalho Chehab
     
  • 63ac85174   docs: kernel-doc.rst: better describe kernel-doc arguments ... Browse Code »

    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

    Mauro Carvalho Chehab
     

20 Oct, 2017

1 commit

27 Aug, 2017

1 commit

24 Jul, 2017

1 commit

18 Jul, 2017

5 commits

16 May, 2017

3 commits

09 Mar, 2017

2 commits

  • db6ccf23e   docs-rst: automatically convert Graphviz and SVG images ... Browse Code »

    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
    Cc: Laurent Pinchart
    Tested-by: Mauro Carvalho Chehab
    Tested-by: Daniel Vetter
    Signed-off-by: Daniel Vetter (v2 - v5)
    Signed-off-by: Markus Heiser (v1, v6)
    Signed-off-by: Jonathan Corbet

    Markus Heiser
     
  • c3c53600f   doc: Explain light-handed markup preference a bit better ... Browse Code »

    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
    Cc: Peter Zijlstra
    Cc: Jani Nikula
    Cc: Mauro Carvalho Chehab
    Signed-off-by: Daniel Vetter
    Signed-off-by: Jonathan Corbet

    Daniel Vetter
     

01 Dec, 2016

1 commit

  • c33966566   docs-rst: parse-headers.pl: cleanup the documentation ... Browse Code »

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

    Mauro Carvalho Chehab
     

20 Nov, 2016

4 commits