[PATCH] drm/doc: Document kapi doc expectations

[PATCH] drm/doc: Document kapi doc expectations

[Daniel Vetter]

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

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH] drm/doc: Document kapi doc expectations

[Sean Paul]

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

Wholeheartedly-Acked-by: Sean Paul <sean@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
> +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 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
> 

-- 
Sean Paul, Software Engineer, Google / Chromium OS
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH] drm/doc: Document kapi doc expectations

[Sam Ravnborg]

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,
s/documentations/documentation?

> and we can bake this in as a requirements subsystem wide.
> 
> 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>
> ---
For what it is worth...
Acked-by: Sam Ravnborg <sam@ravnborg.org>

	Sam
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH] drm/doc: Document kapi doc expectations

[Daniel Vetter]

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

From irc:

Acked-by: Maxime Ripard <maxime.ripard@bootlin.com>

> ---
> 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
> +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 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
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [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@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>
> ---
> 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@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
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH] drm/doc: Document kapi doc expectations

[Emil Velikov]

On Thu, 4 Jul 2019 at 09:39, Daniel Vetter <daniel@ffwll.ch> wrote:
>
> 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@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>
>
> From irc:
>
> Acked-by: Maxime Ripard <maxime.ripard@bootlin.com>
>
Fwiw:
Acked-by: Emil Velikov <emil.velikov@collabora.com>

-Emil
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH] drm/doc: Document kapi doc expectations

[Daniel Vetter]

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

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

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH] drm/doc: Document kapi doc expectations

[Daniel Vetter]

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
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH] drm/doc: Document kapi doc expectations

[Daniel Vetter]

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

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel