Documentation/process/maintainer-tip.rst

Source file repositories/reference/linux-study-clean/Documentation/process/maintainer-tip.rst

File Facts

System
Linux kernel
Corpus path
Documentation/process/maintainer-tip.rst
Extension
.rst
Size
27758 bytes
Lines
849
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct bar_order {
		unsigned int	guest_id;
		int		ordered_item;
		struct menu	*menu;
	};

Please avoid documenting struct members within the declaration, because
this often results in strangely formatted comments and the struct members
become obfuscated::

	struct bar_order {
		unsigned int	guest_id; /* Unique guest id */
		int		ordered_item;
		/* Pointer to a menu instance which contains all the drinks */
		struct menu	*menu;
	};

Instead, please consider using the kernel-doc format in a comment preceding
the struct declaration, which is easier to read and has the added advantage
of including the information in the kernel documentation, for example, as
follows::


	/**
	 * struct bar_order - Description of a bar order
	 * @guest_id:		Unique guest id
	 * @ordered_item:	The item number from the menu
	 * @menu:		Pointer to the menu from which the item
	 *  			was ordered
	 *
	 * Supplementary information for using the struct.
	 *
	 * Note, that the struct member descriptors above are arranged
	 * in a tabular fashion.
	 */
	struct bar_order {
		unsigned int	guest_id;
		int		ordered_item;
		struct menu	*menu;
	};

Static struct initializers must use C99 initializers and should also be
aligned in a tabular fashion::

	static struct foo statfoo = {
		.a		= 0,
		.plain_integer	= CONSTANT_DEFINE_OR_ENUM,
		.bar		= &statbar,
	};

Note that while C99 syntax allows the omission of the final comma,
we recommend the use of a comma on the last line because it makes
reordering and addition of new lines easier, and makes such future
patches slightly easier to read as well.

Line breaks
^^^^^^^^^^^

Restricting line length to 80 characters makes deeply indented code hard to
read.  Consider breaking out code into helper functions to avoid excessive
line breaking.

The 80 character rule is not a strict rule, so please use common sense when
breaking lines. Especially format strings should never be broken up.

When splitting function declarations or function calls, then please align
the first argument in the second line with the first argument in the first
line::

  static int long_function_name(struct foobar *barfoo, unsigned int id,

Annotation

Implementation Notes