Merge tag 'docs-5.16' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
 "This is a relatively unexciting cycle for documentation.

   - Some small scripts/kerneldoc fixes

   - More Chinese translation work, but at a much reduced rate.

   - The tip-tree maintainer's handbook

  ...plus the usual array of build fixes, typo fixes, etc"

* tag 'docs-5.16' of git://git.lwn.net/linux: (53 commits)
  kernel-doc: support DECLARE_PHY_INTERFACE_MASK()
  docs/zh_CN: add core-api xarray translation
  docs/zh_CN: add core-api assoc_array translation
  speakup: Fix typo in documentation "boo" -> "boot"
  docs: submitting-patches: make section about the Link: tag more explicit
  docs: deprecated.rst: Clarify open-coded arithmetic with literals
  scripts: documentation-file-ref-check: fix bpf selftests path
  scripts: documentation-file-ref-check: ignore hidden files
  coding-style.rst: trivial: fix location of driver model macros
  docs: f2fs: fix text alignment
  docs/zh_CN add PCI pci.rst translation
  docs/zh_CN add PCI index.rst translation
  docs: translations: zh_CN: memory-hotplug.rst: fix a typo
  docs: translations: zn_CN: irq-affinity.rst: add a missing extension
  block: add documentation for inflight
  scripts: kernel-doc: Ignore __alloc_size() attribute
  docs: pdfdocs: Adjust \headheight for fancyhdr
  docs: UML: user_mode_linux_howto_v2 edits
  docs: use the lore redirector everywhere
  docs: proc.rst: mountinfo: align columns
  ...

1 files changed, 37 insertions, 2 deletions

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 42969ab37b34..03eb53fd029a 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -480,13 +480,48 @@ closing function brace line.  E.g.:
 	}
 	EXPORT_SYMBOL(system_is_up);
 
+6.1) Function prototypes
+************************
+
 In function prototypes, include parameter names with their data types.
 Although this is not required by the C language, it is preferred in Linux
 because it is a simple way to add valuable information for the reader.
 
-Do not use the ``extern`` keyword with function prototypes as this makes
+Do not use the ``extern`` keyword with function declarations as this makes
 lines longer and isn't strictly necessary.
 
+When writing function prototypes, please keep the `order of elements regular
+<https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_.
+For example, using this function declaration example::
+
+ __init void * __must_check action(enum magic value, size_t size, u8 count,
+				   char *fmt, ...) __printf(4, 5) __malloc;
+
+The preferred order of elements for a function prototype is:
+
+- storage class (below, ``static __always_inline``, noting that ``__always_inline``
+  is technically an attribute but is treated like ``inline``)
+- storage class attributes (here, ``__init`` -- i.e. section declarations, but also
+  things like ``__cold``)
+- return type (here, ``void *``)
+- return type attributes (here, ``__must_check``)
+- function name (here, ``action``)
+- function parameters (here, ``(enum magic value, size_t size, u8 count, char *fmt, ...)``,
+  noting that parameter names should always be included)
+- function parameter attributes (here, ``__printf(4, 5)``)
+- function behavior attributes (here, ``__malloc``)
+
+Note that for a function **definition** (i.e. the actual function body),
+the compiler does not allow function parameter attributes after the
+function parameters. In these cases, they should go after the storage
+class attributes (e.g. note the changed position of ``__printf(4, 5)``
+below, compared to the **declaration** example above)::
+
+ static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value,
+		size_t size, u8 count, char *fmt, ...) __malloc
+ {
+	...
+ }
 
 7) Centralized exiting of functions
 -----------------------------------
@@ -855,7 +890,7 @@ Kernel messages do not have to be terminated with a period.
 
 Printing numbers in parentheses (%d) adds no value and should be avoided.
 
-There are a number of driver model diagnostic macros in <linux/device.h>
+There are a number of driver model diagnostic macros in <linux/dev_printk.h>
 which you should use to make sure messages are matched to the right device
 and driver, and are tagged with the right level:  dev_err(), dev_warn(),
 dev_info(), and so forth.  For messages that aren't associated with a