Documentation/doc-guide/contributing.rst

Source file repositories/reference/linux-study-clean/Documentation/doc-guide/contributing.rst

File Facts

System
Linux kernel
Corpus path
Documentation/doc-guide/contributing.rst
Extension
.rst
Size
13469 bytes
Lines
301
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: exported/initcall integration point
Status
integration implementation candidate

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

.. SPDX-License-Identifier: GPL-2.0

How to help improve kernel documentation
========================================

Documentation is an important part of any software-development project.
Good documentation helps to bring new developers in and helps established
developers work more effectively.  Without top-quality documentation, a lot
of time is wasted in reverse-engineering the code and making avoidable
mistakes.

Unfortunately, the kernel's documentation currently falls far short of what
it needs to be to support a project of this size and importance.

This guide is for contributors who would like to improve that situation.
Kernel documentation improvements can be made by developers at a variety of
skill levels; they are a relatively easy way to learn the kernel process in
general and find a place in the community.  The bulk of what follows is the
documentation maintainer's list of tasks that most urgently need to be
done.

The documentation TODO list
---------------------------

There is an endless list of tasks that need to be carried out to get our
documentation to where it should be.  This list contains a number of
important items, but is far from exhaustive; if you see a different way to
improve the documentation, please do not hold back!

Addressing warnings
~~~~~~~~~~~~~~~~~~~

The documentation build currently spews out an unbelievable number of
warnings.  When you have that many, you might as well have none at all;
people ignore them, and they will never notice when their work adds new
ones.  For this reason, eliminating warnings is one of the highest-priority
tasks on the documentation TODO list.  The task itself is reasonably
straightforward, but it must be approached in the right way to be
successful.

Warnings issued by a compiler for C code can often be dismissed as false
positives, leading to patches aimed at simply shutting the compiler up.
Warnings from the documentation build almost always point at a real
problem; making those warnings go away requires understanding the problem
and fixing it at its source.  For this reason, patches fixing documentation
warnings should probably not say "fix a warning" in the changelog title;
they should indicate the real problem that has been fixed.

Another important point is that documentation warnings are often created by
problems in kerneldoc comments in C code.  While the documentation
maintainer appreciates being copied on fixes for these warnings, the
documentation tree is often not the right one to actually carry those
fixes; they should go to the maintainer of the subsystem in question.

For example, in a documentation build I grabbed a pair of warnings nearly
at random::

  ./drivers/devfreq/devfreq.c:1818: warning: bad line:
  	- Resource-managed devfreq_register_notifier()
  ./drivers/devfreq/devfreq.c:1854: warning: bad line:
	- Resource-managed devfreq_unregister_notifier()

(The lines were split for readability).

A quick look at the source file named above turned up a couple of kerneldoc
comments that look like this::

  /**
   * devm_devfreq_register_notifier()
	  - Resource-managed devfreq_register_notifier()

Annotation

Implementation Notes