drm/doc: Document kapi doc expectations
diff mbox series

Message ID 20190704145054.5701-1-daniel.vetter@ffwll.ch
State New
Headers show
Series
  • drm/doc: Document kapi doc expectations
Related show

Commit Message

Daniel Vetter July 4, 2019, 2:50 p.m. UTC
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>
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 | 16 ++++++++++++++++
 Documentation/gpu/todo.rst         | 13 -------------
 2 files changed, 16 insertions(+), 13 deletions(-)

Comments

Daniel Vetter July 5, 2019, 3:14 p.m. UTC | #1
On Thu, Jul 04, 2019 at 04:50:54PM +0200, Daniel Vetter wrote:
> 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>
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>

From irc:

Acked-by: Alex Deucher <alexdeucher@gmail.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 | 16 ++++++++++++++++
>  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 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
>  ------------------------
>  
> -- 
> 2.20.1
>
Daniel Vetter July 19, 2019, 1:04 p.m. UTC | #2
On Fri, Jul 05, 2019 at 05:14:47PM +0200, Daniel Vetter wrote:
> On Thu, Jul 04, 2019 at 04:50:54PM +0200, Daniel Vetter wrote:
> > 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>
> > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> 
> From irc:
> 
> Acked-by: Alex Deucher <alexdeucher@gmail.com>

I guess that's enough acks, applied for 5.4 in drm-misc-next.
-Daniel

> 
> > 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 | 16 ++++++++++++++++
> >  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 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
> >  ------------------------
> >  
> > -- 
> > 2.20.1
> > 
> 
> -- 
> Daniel Vetter
> Software Engineer, Intel Corporation
> http://blog.ffwll.ch

Patch
diff mbox series

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