[PATCH] drm/doc: Document kapi doc expectations

[Laurent Pinchart]

Hi Daniel,

Thank you for the patch.

On Tue, Jun 25, 2019 at 10:36:44PM +0200, Daniel Vetter 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.
> 
> Acked-by: Jani Nikula <jani.nikula at intel.com>
> 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>
> ---
> resending stand-alone for more visibility and a-b gathering.
> -Daniel
> ---
>  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

s/should/shall/

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

Should we make it clear here that kerneldoc syntax is perfectly fine but
that the comment should start with /* instead of /** ? kerneldoc is a
widely understood syntax among kernel developers, so it makes sense to
document internal functions (when needed) with the same syntax. The only
thing we don't want is to have those functions ending up in the
generated documentation.

With this addressed,

Acked-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>

> +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 e717f280f9ae..db88969a56ee 100644
> --- a/Documentation/gpu/todo.rst
> +++ b/Documentation/gpu/todo.rst
> @@ -301,19 +301,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
>  ------------------------
>  

-- 
Regards,

Laurent Pinchart