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@xxxxxxxxx> > Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx> > Cc: Laurent Pinchart <laurent.pinchart@xxxxxxxxxxxxxxxx> > Cc: Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> > Cc: David Airlie <airlied@xxxxxxxx> > Cc: Daniel Vetter <daniel@xxxxxxxx> > Cc: Maarten Lankhorst <maarten.lankhorst@xxxxxxxxxxxxxxx> > Cc: Maxime Ripard <maxime.ripard@xxxxxxxxxxx> > Cc: Sean Paul <sean@xxxxxxxxxx> Wholeheartedly-Acked-by: Sean Paul <sean@xxxxxxxxxx> > --- > 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@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/dri-devel
