[0/7] Documentation warning reduction

I've come to the conclusion that we really need to make the docs build
quieter.  Here's a small step in that direction: getting rid of all of the
"no structured comments found" warnings.  Such warnings are usually the
result of kerneldoc comments being moved elsewhere, so this took a bit of
git archeology to do; hopefully I got it right.

Each patch stands alone, so if the DRM folks want to carry the last two
themselves, that's fine, just let me know.

Jonathan Corbet (7):
  docs: Get module_init() docs from module.h
  docs: Do not include kerneldoc comments from kernel/sys.c
  docs: Do not include from .../seqno-fence.c
  docs: Get the struct cmbdata kernel doc from the right file
  docs: Do not include from drivers/scsi/constants.c
  docs: Do not include from include/drm/drm_color_mgmt.h
  docs: Use :internal: for include/drm/drm_syncobj.h

 Documentation/driver-api/basics.rst       | 5 +----
 Documentation/driver-api/dma-buf.rst      | 3 ---
 Documentation/driver-api/s390-drivers.rst | 2 +-
 Documentation/driver-api/scsi.rst         | 8 --------
 Documentation/gpu/drm-kms.rst             | 3 ---
 Documentation/gpu/drm-mm.rst              | 2 +-
 6 files changed, 3 insertions(+), 20 deletions(-)

-- 
2.9.4

On Mon, Jul 17, 2017 at 03:00:47PM -0600, Jonathan Corbet wrote:
> Commit 8f2e045ec878 (drm/color: un-inline drm_color_lut_extract()) moved

> the only kerneldoc comment out of include/drm/drm_color_mgmt.h, leading to

> this warning:

> 

>     ./include/drm/drm_color_mgmt.h:1: warning: no structured comments found

> 

> That comment is already picked up in drm_color_mgmt.c, so just delete the

> directive.

> 

> CC: dri-devel@lists.freedesktop.org

> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

> ---


We have something like this already queued for 4.14, but if you want to
fix all the warnings in 4.13 already I think that makes sense. But I'll
leave that to you and merging through docs-fixes.

Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>


>  Documentation/gpu/drm-kms.rst | 3 ---

>  1 file changed, 3 deletions(-)

> 

> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst

> index 2d77c9580164..0749000ab3d7 100644

> --- a/Documentation/gpu/drm-kms.rst

> +++ b/Documentation/gpu/drm-kms.rst

> @@ -523,9 +523,6 @@ Color Management Properties

>  .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c

>     :doc: overview

>  

> -.. kernel-doc:: include/drm/drm_color_mgmt.h

> -   :internal:

> -

>  .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c

>     :export:

>  

> -- 

> 2.9.4

> 

> --

> To unsubscribe from this list: send the line "unsubscribe linux-doc" in

> the body of a message to majordomo@vger.kernel.org

> More majordomo info at  http://vger.kernel.org/majordomo-info.html


-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

On Tue, 18 Jul 2017 08:42:42 +0200
Daniel Vetter <daniel@ffwll.ch> wrote:

> > Commit 8f2e045ec878 (drm/color: un-inline drm_color_lut_extract()) moved

> > the only kerneldoc comment out of include/drm/drm_color_mgmt.h, leading to

> > this warning:

> > 

> >     ./include/drm/drm_color_mgmt.h:1: warning: no structured comments found

> > 

> > That comment is already picked up in drm_color_mgmt.c, so just delete the

> > directive.

> > 

> > CC: dri-devel@lists.freedesktop.org

> > Signed-off-by: Jonathan Corbet <corbet@lwn.net>

> > ---  

> 

> We have something like this already queued for 4.14, but if you want to

> fix all the warnings in 4.13 already I think that makes sense. But I'll

> leave that to you and merging through docs-fixes.


4.14 was my plan too; I think I've sent Linus enough churn for this cycle
already...:)  Since you have it queued, I'll just drop mine.  Plenty of
other warnings to beat my head against.

Thanks,

jon