[Intel-gfx] [PATCH 59/59] drm/doc: Document kapi doc expectations

[Jani Nikula]

On Fri, 14 Jun 2019, Daniel Vetter <daniel.vetter at ffwll.ch> wrote:
> 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 at intel.com>
> Cc: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> Cc: Jani Nikula <jani.nikula at linux.intel.com>
> Cc: David Airlie <airlied at linux.ie>
> Cc: Daniel Vetter <daniel at ffwll.ch>
> Cc: Maarten Lankhorst <maarten.lankhorst at linux.intel.com>
> Cc: Maxime Ripard <maxime.ripard at bootlin.com>
> Cc: Sean Paul <sean at poorly.run>

Acked-by: Jani Nikula <jani.nikula at intel.com>

> ---
>  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
>  ------------------------

-- 
Jani Nikula, Intel Open Source Graphics Center