drm/doc: Document kapi doc expectations

Commit Message

Daniel Vetter June 25, 2019, 8:36 p.m. UTC

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 <[e-mail]>
Signed-off-by: Daniel Vetter <[e-mail]>
Cc: Laurent Pinchart <[e-mail]>
Cc: Jani Nikula <[e-mail]>
Cc: David Airlie <[e-mail]>
Cc: Daniel Vetter <[e-mail]>
Cc: Maarten Lankhorst <[e-mail]>
Cc: Maxime Ripard <[e-mail]>
Cc: Sean Paul <[e-mail]>
---
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(-)

Comments

Sean Paul June 25, 2019, 8:42 p.m. UTC | #1

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 <[e-mail]>
> Signed-off-by: Daniel Vetter <[e-mail]>
> Cc: Laurent Pinchart <[e-mail]>
> Cc: Jani Nikula <[e-mail]>
> Cc: David Airlie <[e-mail]>
> Cc: Daniel Vetter <[e-mail]>
> Cc: Maarten Lankhorst <[e-mail]>
> Cc: Maxime Ripard <[e-mail]>
> Cc: Sean Paul <[e-mail]>

Wholeheartedly-Acked-by: Sean Paul <[e-mail]>

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

Sam Ravnborg June 25, 2019, 8:47 p.m. UTC | #2

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 <[e-mail]>
> Signed-off-by: Daniel Vetter <[e-mail]>
> Cc: Laurent Pinchart <[e-mail]>
> Cc: Jani Nikula <[e-mail]>
> Cc: David Airlie <[e-mail]>
> Cc: Daniel Vetter <[e-mail]>
> Cc: Maarten Lankhorst <[e-mail]>
> Cc: Maxime Ripard <[e-mail]>
> Cc: Sean Paul <[e-mail]>
> ---
For what it is worth...
Acked-by: Sam Ravnborg <[e-mail]>

	Sam

Daniel Vetter July 4, 2019, 8:39 a.m. UTC | #3

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 <[e-mail]>
> Signed-off-by: Daniel Vetter <[e-mail]>
> Cc: Laurent Pinchart <[e-mail]>
> Cc: Jani Nikula <[e-mail]>
> Cc: David Airlie <[e-mail]>
> Cc: Daniel Vetter <[e-mail]>
> Cc: Maarten Lankhorst <[e-mail]>
> Cc: Maxime Ripard <[e-mail]>
> Cc: Sean Paul <[e-mail]>

From irc:

Acked-by: Maxime Ripard <[e-mail]>

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

Laurent Pinchart July 4, 2019, 12:38 p.m. UTC | #4

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 <[e-mail]>
> Signed-off-by: Daniel Vetter <[e-mail]>
> Cc: Laurent Pinchart <[e-mail]>
> Cc: Jani Nikula <[e-mail]>
> Cc: David Airlie <[e-mail]>
> Cc: Daniel Vetter <[e-mail]>
> Cc: Maarten Lankhorst <[e-mail]>
> Cc: Maxime Ripard <[e-mail]>
> Cc: Sean Paul <[e-mail]>
> ---
> 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 <[e-mail]>

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

Emil Velikov July 4, 2019, 2:01 p.m. UTC | #5

On Thu, 4 Jul 2019 at 09:39, Daniel Vetter <[e-mail]> 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 <[e-mail]>
> > Signed-off-by: Daniel Vetter <[e-mail]>
> > Cc: Laurent Pinchart <[e-mail]>
> > Cc: Jani Nikula <[e-mail]>
> > Cc: David Airlie <[e-mail]>
> > Cc: Daniel Vetter <[e-mail]>
> > Cc: Maarten Lankhorst <[e-mail]>
> > Cc: Maxime Ripard <[e-mail]>
> > Cc: Sean Paul <[e-mail]>
>
> From irc:
>
> Acked-by: Maxime Ripard <[e-mail]>
>
Fwiw:
Acked-by: Emil Velikov <[e-mail]>

-Emil

Patch

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