Commit 1e990736 authored by Daniel Vetter's avatar Daniel Vetter

drm/doc: Document kapi doc expectations

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

v2: Improve wording a bit (Laurent), fix typo in commit message (Sam).
Acked-by: default avatarEmil Velikov <emil.velikov@collabora.com>
Acked-by: default avatarSean Paul <sean@poorly.run>
Acked-by: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: default avatarMaxime Ripard <maxime.ripard@bootlin.com>
Acked-by: default avatarSam Ravnborg <sam@ravnborg.org>
Acked-by: default avatarJani Nikula <jani.nikula@intel.com>
Acked-by: default avatarAlex Deucher <alexdeucher@gmail.com>
Signed-off-by: default avatarDaniel 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>
Link: https://patchwork.freedesktop.org/patch/msgid/20190704145054.5701-1-daniel.vetter@ffwll.ch
parent e362cc6a
...@@ -51,6 +51,22 @@ and "FIXME" where the interface could be cleaned up. ...@@ -51,6 +51,22 @@ and "FIXME" where the interface could be cleaned up.
Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`. 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. You may use kerneldoc syntax in the comment, but it shall not
start with a /** kerneldoc marker. Similar for data structures, annotate
anything entirely private with ``/* private: */`` comments as per the
documentation guide.
Getting Started Getting Started
=============== ===============
......
...@@ -308,19 +308,6 @@ In the end no .c file should need to include ``drmP.h`` anymore. ...@@ -308,19 +308,6 @@ In the end no .c file should need to include ``drmP.h`` anymore.
Contact: Daniel Vetter 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 Make panic handling work
------------------------ ------------------------
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment