| Message ID | 20190704145054.5701-1-daniel.vetter@ffwll.ch (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm/doc: Document kapi doc expectations | expand |
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 >
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
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 ------------------------