Acked-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NWolfram Sang <wsa+renesas@sang-engineering.com>
Link: https://lore.kernel.org/r/20210127104343.5647-1-wsa+renesas@sang-engineering.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

The kernel-doc markups on this file are weird: they don't
follow what's specified at:

	Documentation/doc-guide/kernel-doc.rst

In particular, markups should use this format:
        identifier - description

and not this:
	identifier(args)

The way the definitions are inside this file cause the
parser to completely miss the identifier name of each
function.

This prevents improving the script to do some needed validation
tests.

Address this part. Yet, furter changes are needed in order
for it to fully follow the specs.
Acked-by: NKees Cook <keescook@chromium.org>
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/8383758160fdb4fcbb2ac56beeb874ca6dffc6b9.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/2dc136ff6290d7c8919599d21bee244f31647c8c.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Some identifiers have different names between their prototypes
and the kernel-doc markup.
Acked-by: NMike Rapoport <rppt@linux.ibm.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/f3c65f61367993a607f9daf9dc1a3bdab1f0a040.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/1963266e84c6fb0154602f276b04887c85f80bd3.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/889cfb141a98ae06d5bc79b744786ec2e8f92d93.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

There are some common comments marked, instead, with kernel-doc
notation, which won't work.

While here, rename an identifier, in order to match the
function prototype below kernel-doc markup.
Acked-by: NRichard Gong <richard.gong@linux.intel.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/02a1eb47767e01e875d8840805b8b2d4f3c6bdee.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

The documented struct is psz_head and not psz_buffer.
Reviewed-by: NKees Cook <keescook@chromium.org>
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/a67ca4d12c3ef277dadb9e0d0df8450158e637cc.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Two markups are at the wrong place. Kernel-doc only
support having the comment just before the identifier.

Also, some identifiers have different names between their
prototypes and the kernel-doc markup.
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/96b1e1b388600ab092331f6c4e88ff8e8779ce6c.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Probaly this was due to a cut and paste issue.
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/e23e64983788a51dd9099e2b0d881e1f64ecbc5b.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

The kernel-doc markup inside share.c is actually for
__parport_register_driver. The actual goal seems to be
to document parport_register_driver().

So, fix the existing markup and add a new one.
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/dc0778af8c466cc667409ead05876a5cfd3cbece.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Fix typos (punctuation, grammar, spelling) in afs.rst.
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Cc: David Howells <dhowells@redhat.com>
Cc: linux-afs@lists.infradead.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/r/20210117213351.1075-1-rdunlap@infradead.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

It's a unused tag with a incorrect big name but just for mips arch.
So remove it.
Signed-off-by: NAlex Shi <alex.shi@linux.alibaba.com>
Cc: Yanteng Si <siyanteng@loongson.cn>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/r/20210121024113.16344-1-alex.shi@linux.alibaba.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

There are two EP9312, one of them should be 9315
Signed-off-by: NYanteng Si <siyanteng@loongson.cn>
Link: https://lore.kernel.org/r/20210119030320.2860870-1-siyanteng@loongson.cnSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Commit adab66b7 ("Revert: "ring-buffer: Remove HAVE_64BIT_ALIGNED_ACCESS"")
added the config HAVE_64BIT_ALIGNED_ACCESS back into arch/Kconfig with this
revert. In the meantime, commit c9b54d6f ("docs: move other kAPI
documents to core-api") changed ./Documentation/unaligned-memory-access.txt
to ./Documentation/core-api/unaligned-memory-access.rst.

Fortunately, ./scripts/documentation-file-ref-check detects this and warns
about this broken reference.

Update the file reference in arch/Kconfig.

Fixes: adab66b7 ("Revert: "ring-buffer: Remove HAVE_64BIT_ALIGNED_ACCESS"")
Signed-off-by: NLukas Bulwahn <lukas.bulwahn@gmail.com>
Link: https://lore.kernel.org/r/20210119095326.13896-1-lukas.bulwahn@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Due to an extra empty line between the option and its description
it is rendered not like in other places.

Remove the empty lines to fix.
Signed-off-by: NKir Kolyshkin <kolyshkin@gmail.com>
Acked-by: NTejun Heo <tj@kernel.org>
Link: https://lore.kernel.org/r/20210120001824.385168-11-kolyshkin@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Improper Capitalization.
Signed-off-by: NKir Kolyshkin <kolyshkin@gmail.com>
Acked-by: NTejun Heo <tj@kernel.org>
Link: https://lore.kernel.org/r/20210120001824.385168-10-kolyshkin@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

These two places are rendered like a table in the source (rst) code,
but they are seen as plain text by formatters, and thus are joined
together into a single line, e.g.:

> “root” - a partition root “member” - a non-root member of a partition

This is definitely not what was intended.

To fix, use table formatting, like in other places.
Signed-off-by: NKir Kolyshkin <kolyshkin@gmail.com>
Acked-by: NTejun Heo <tj@kernel.org>
Link: https://lore.kernel.org/r/20210120001824.385168-9-kolyshkin@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Due to an extra vertical whitespace, this was not recognised
as a definition list entry, and thus was not rendered like
the rest of cgroupfs files.
Signed-off-by: NKir Kolyshkin <kolyshkin@gmail.com>
Acked-by: NTejun Heo <tj@kernel.org>
Link: https://lore.kernel.org/r/20210120001824.385168-8-kolyshkin@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

- fix a typo (mempry -> memory) in a file name;
- add space before "(" where appropriate.
Signed-off-by: NKir Kolyshkin <kolyshkin@gmail.com>
Acked-by: NTejun Heo <tj@kernel.org>
Link: https://lore.kernel.org/r/20210120001824.385168-7-kolyshkin@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Signed-off-by: NKir Kolyshkin <kolyshkin@gmail.com>
Acked-by: NTejun Heo <tj@kernel.org>
Link: https://lore.kernel.org/r/20210120001824.385168-6-kolyshkin@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Signed-off-by: NKir Kolyshkin <kolyshkin@gmail.com>
Acked-by: NTejun Heo <tj@kernel.org>
Link: https://lore.kernel.org/r/20210120001824.385168-4-kolyshkin@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Fix the rendering of the paragraph. Before the fix, the first line is
rendered in bold (I'm not quite sure why) and is also separated from the
rest of the paragraph, which is rendered with an indent.
Signed-off-by: NKir Kolyshkin <kolyshkin@gmail.com>
Acked-by: NTejun Heo <tj@kernel.org>
Link: https://lore.kernel.org/r/20210120001824.385168-3-kolyshkin@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Since commit d6a3b247 these three lines are merged into one by the
RST processor, making it hard to read. Use bullet points to separate
the entries, like it's done in other similar places.
Signed-off-by: NKir Kolyshkin <kolyshkin@gmail.com>
Acked-by: NTejun Heo <tj@kernel.org>
Link: https://lore.kernel.org/r/20210120001824.385168-2-kolyshkin@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Kernel-doc currently expects that the kernel-doc markup to come
just before the function/enum/struct/union/typedef prototype.

Yet, if it find things like:

	/**
	 * refcount_add - add a value to a refcount
	 * @i: the value to add to the refcount
	 * @r: the refcount
	 */
	static inline void __refcount_add(int i, refcount_t *r, int *oldp);
	static inline void refcount_add(int i, refcount_t *r);

Kernel-doc will do the wrong thing:

	foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add'
	.. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp)

	   add a value to a refcount

	**Parameters**

	``int i``
	  the value to add to the refcount

	``refcount_t *r``
	  the refcount

	``int *oldp``
	  *undescribed*

Basically, it will document "__refcount_add" with the kernel-doc
markup for refcount_add.

If both functions have the same arguments, this won't even
produce any warning!

Add a logic to check if the kernel-doc identifier matches the actual
name of the C function or data structure that will be documented.
Signed-off-by: NMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/081546f141a496d6cabb99a4adc140444c705e93.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Signed-off-by: NRolf Eike Beer <eb@emlix.com>
Link: https://lore.kernel.org/r/2338863.uUFqZTUbry@devpool47Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Remove the make headers_check step from submit-checklist.rst as this is
no longer functional.
Signed-off-by: NMilan Lakhani <milan.lakhani@codethink.co.uk>
Link: https://lore.kernel.org/r/1610458861-2832-1-git-send-email-milan.lakhani@codethink.co.ukSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Plenty of architectures are already supported and this adds ARM
support.
Signed-off-by: NMarc Koderer <marc@koderer.com>
Acked-by: NMasami Hiramatsu <mhiramat@kernel.org>
Link: https://lore.kernel.org/r/20210112154054.17138-1-marc@koderer.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Clear-up any confusion surrounding the Fixes: tag with regards to the
need to Cc: the stable mailing list when submitting stable patch
candidates.
Signed-off-by: NLee Jones <lee.jones@linaro.org>
Reviewed-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/r/20210113163315.1331064-1-lee.jones@linaro.orgSigned-off-by: NJonathan Corbet <corbet@lwn.net>

This commit links Korean translation of 'memory-barriers.txt' in the
translations index rst file as the original version is linked in
'Documentation/staging/index.rst'.
Signed-off-by: NSeongJae Park <sjpark@amazon.de>
Link: https://lore.kernel.org/r/20210117100931.9347-4-sj38.park@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Translate this commit to Korean:

    da514157 ("docs: make reporting-bugs.rst obsolete")
Signed-off-by: NSeongJae Park <sjpark@amazon.de>
Link: https://lore.kernel.org/r/20210117100931.9347-3-sj38.park@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Apply this commit to Korean:

    e7b4311e ("Replace HTTP links with HTTPS ones: Documentation/process")
Signed-off-by: NSeongJae Park <sjpark@amazon.de>
Link: https://lore.kernel.org/r/20210117100931.9347-2-sj38.park@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

The file Documentation/process/howto.rst points to bugzilla.kernel.org
as the primary place to report kernel bugs to. For most of the kernel
that's the wrong place, as the MAINTAINERS file shows. Adjust those
sections to make them match current practice.

This change also removes a contradiction with the recently added text
Documentation/admin-guide/reporting-issues.rst, which is a reason for a
'this needs further discussion' warning note in there. The change is
thus a prerequisite to remove that warning, nevertheless it is left for
now to make sure people review the text's approach more carefully.
Signed-off-by: NThorsten Leemhuis <linux@leemhuis.info>
Acked-by: NRandy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20210116143542.69199-1-linux@leemhuis.infoSigned-off-by: NJonathan Corbet <corbet@lwn.net>

The Chinese mips translations refer to non-existing labels in the original
documentation. Hence, make htmldocs warns about those undefined labels on
all files in ./Documentation/translations/zh_CN/mips/.

Replace the references to non-existing labels with suitable doc references.
Signed-off-by: NLukas Bulwahn <lukas.bulwahn@gmail.com>
Fixes: 419b1d4e ("doc/zh_CN: add mips ingenic-tcu.rst translation")
Fixes: 72bc9d08 ("doc/zh_CN: add mips features.rst translation")
Fixes: 7fd3954b ("doc/zh_CN: add mips booting.rst translation")
Fixes: b8e724fd ("doc/zh_CN: add mips index.rst translation")
Reported-by: NStephen Rothwell <sfr@canb.auug.org.au>
Link: https://lore.kernel.org/r/20210113070557.28792-1-lukas.bulwahn@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

Commit 419b1d4e ("doc/zh_CN: add mips ingenic-tcu.rst translation")
introduces a warning with make htmldocs:

  ./Documentation/translations/zh_CN/mips/ingenic-tcu.rst:
    61: WARNING: Malformed table. Text in column margin in table line 6.

Adjust the table markup to address this warning.
Signed-off-by: NLukas Bulwahn <lukas.bulwahn@gmail.com>
Fixes: 419b1d4e ("doc/zh_CN: add mips ingenic-tcu.rst translation")
Reviewed-by: NAlex Shi <alex.shi@linux.alibaba.com>
Reported-by: NStephen Rothwell <sfr@canb.auug.org.au>
Link: https://lore.kernel.org/r/20210113070023.25064-1-lukas.bulwahn@gmail.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>

This patch translates Documentation/mips/ingenic-tcu.rst into Chinese.
Signed-off-by: NYanteng Si <siyanteng@loongson.cn>
Reviewed-by: NAlex Shi <alex.shi@linux.alibaba.com>
Link: https://lore.kernel.org/r/20210112115259.217944-4-siyanteng@loongson.cnSigned-off-by: NJonathan Corbet <corbet@lwn.net>

This patch translates Documentation/mips/features.rst into Chinese.
Signed-off-by: NYanteng Si <siyanteng@loongson.cn>
Reviewed-by: NAlex Shi <alex.shi@linux.alibaba.com>
Link: https://lore.kernel.org/r/20210112115259.217944-3-siyanteng@loongson.cnSigned-off-by: NJonathan Corbet <corbet@lwn.net>

This patch translates Documentation/mips/booting.rst into Chinese.
Signed-off-by: NYanteng Si <siyanteng@loongson.cn>
Reviewed-by: NAlex Shi <alex.shi@linux.alibaba.com>
Link: https://lore.kernel.org/r/20210112115259.217944-2-siyanteng@loongson.cnSigned-off-by: NJonathan Corbet <corbet@lwn.net>

This patch translates Documentation/mips/index.rst into Chinese.
Signed-off-by: NYanteng Si <siyanteng@loongson.cn>
Reviewed-by: NAlex Shi <alex.shi@linux.alibaba.com>
Reviewed-by: NJiaxun Yang <jiaxun.yang@flygoat.com>
Link: https://lore.kernel.org/r/20210112115259.217944-1-siyanteng@loongson.cnSigned-off-by: NJonathan Corbet <corbet@lwn.net>

The example file supports many architectures not only x86 and PPC.
Signed-off-by: NMarc Koderer <marc@koderer.com>
Cc: trivial@kernel.org
Link: https://lore.kernel.org/r/20201228060415.2194-1-marc@koderer.comSigned-off-by: NJonathan Corbet <corbet@lwn.net>