[PATCH 59/59] drm/doc: Document kapi doc expectations

Daniel Vetter
2019-06-14T20:37:30Z

We've had this already for anything new. With my drm_prime.c cleanup I
also think documentations for everything already existing is complete,
and we can bake this in as a requirements subsystem wide.

Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: David Airlie <airlied@linux.ie>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Maxime Ripard <maxime.ripard@bootlin.com>
Cc: Sean Paul <sean@poorly.run>
---
Documentation/gpu/introduction.rst | 13 +++++++++++++
Documentation/gpu/todo.rst | 13 -------------
2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst
index fccbe375244d..a94ad6ad1f54 100644
--- a/Documentation/gpu/introduction.rst
+++ b/Documentation/gpu/introduction.rst
@@ -51,6 +51,19 @@ and "FIXME" where the interface could be cleaned up.

Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`.

+Documentation Requirements for kAPI
+-----------------------------------
+
+All kernel APIs exported to other modules must be documented, including their
+datastructures and at least a short introductory section explaining the overall
+concepts. Documentation should be put into the code itself as kerneldoc comments
+as much as reasonable. Do not blindly document everything, but document only
+what's relevant for driver authors: Internal functions of drm.ko and definitely
+static functions should not have formal kerneldoc comments. Use normal C
+comments if you feel like a comment is warranted. Similar for data structures,
+annotate anything entirely private with ``/* private: */`` comments as per the
+documentation guide.
+
Getting Started
===============

diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst
index 026e55c517e1..25878dd048fd 100644
--- a/Documentation/gpu/todo.rst
+++ b/Documentation/gpu/todo.rst
@@ -299,19 +299,6 @@ In the end no .c file should need to include ``drmP.h`` anymore.

Contact: Daniel Vetter

-Add missing kerneldoc for exported functions
---------------------------------------------
-
-The DRM reference documentation is still lacking kerneldoc in a few areas. The
-task would be to clean up interfaces like moving functions around between
-files to better group them and improving the interfaces like dropping return
-values for functions that never fail. Then write kerneldoc for all exported
-functions and an overview section and integrate it all into the drm book.
-
-See https://dri.freedesktop.org/docs/drm/ for what's there already.
-
-Contact: Daniel Vetter
-
Make panic handling work
------------------------

--
2.20.1