diff options
| author | Daniel Vetter <daniel.vetter@ffwll.ch> | 2019-07-04 16:50:54 +0200 |
|---|---|---|
| committer | Daniel Vetter <daniel.vetter@ffwll.ch> | 2019-07-19 15:02:37 +0200 |
| commit | 1e9907362453b9ddf9e73a144bec91f15ca0d536 (patch) | |
| tree | bfeb86e47bdad0e0f504b9056b1e2258ce949469 /Documentation/gpu | |
| parent | e362cc6a247551ead1b3121521ac7a11d397db81 (diff) | |
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: Emil Velikov <emil.velikov@collabora.com>
Acked-by: Sean Paul <sean@poorly.run>
Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: Maxime Ripard <maxime.ripard@bootlin.com>
Acked-by: Sam Ravnborg <sam@ravnborg.org>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Acked-by: Alex Deucher <alexdeucher@gmail.com>
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>
Link: https://patchwork.freedesktop.org/patch/msgid/20190704145054.5701-1-daniel.vetter@ffwll.ch
Diffstat (limited to 'Documentation/gpu')
| -rw-r--r-- | Documentation/gpu/introduction.rst | 16 | ||||
| -rw-r--r-- | Documentation/gpu/todo.rst | 13 |
2 files changed, 16 insertions, 13 deletions
diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst index fccbe375244d..25a56e9c0cfd 100644 --- a/Documentation/gpu/introduction.rst +++ b/Documentation/gpu/introduction.rst @@ -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>`. +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 =============== diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 3f6ecf846263..a38639e96e8b 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -308,19 +308,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 ------------------------ |