dri-devel.lists.freedesktop.org archive mirror
 help / color / mirror / Atom feed
* [PATCH 0/7] Documentation warning reduction
@ 2017-07-17 21:00 Jonathan Corbet
  2017-07-17 21:00 ` [PATCH 1/7] docs: Get module_init() docs from module.h Jonathan Corbet
                   ` (6 more replies)
  0 siblings, 7 replies; 10+ messages in thread
From: Jonathan Corbet @ 2017-07-17 21:00 UTC (permalink / raw)
  To: linux-doc; +Cc: linux-kernel, dri-devel, Jonathan Corbet

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


^ permalink raw reply	[flat|nested] 10+ messages in thread

* [PATCH 1/7] docs: Get module_init() docs from module.h
  2017-07-17 21:00 [PATCH 0/7] Documentation warning reduction Jonathan Corbet
@ 2017-07-17 21:00 ` Jonathan Corbet
  2017-07-17 21:00 ` [PATCH 2/7] docs: Do not include kerneldoc comments from kernel/sys.c Jonathan Corbet
                   ` (5 subsequent siblings)
  6 siblings, 0 replies; 10+ messages in thread
From: Jonathan Corbet @ 2017-07-17 21:00 UTC (permalink / raw)
  To: linux-doc; +Cc: linux-kernel, dri-devel, Jonathan Corbet

The docs build complains:

    ./include/linux/init.h:1: warning: no structured comments found

The problem is that the comments in question were moved to module.h in
commit 0fd972a7d91d (module: relocate module_init from init.h to
module.h).  Fix basics.rst to match.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/driver-api/basics.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index ab82250c7727..cbfb5a825077 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -4,7 +4,7 @@ Driver Basics
 Driver Entry and Exit points
 ----------------------------
 
-.. kernel-doc:: include/linux/init.h
+.. kernel-doc:: include/linux/module.h
    :internal:
 
 Driver device table
-- 
2.9.4

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

^ permalink raw reply related	[flat|nested] 10+ messages in thread

* [PATCH 2/7] docs: Do not include kerneldoc comments from kernel/sys.c
  2017-07-17 21:00 [PATCH 0/7] Documentation warning reduction Jonathan Corbet
  2017-07-17 21:00 ` [PATCH 1/7] docs: Get module_init() docs from module.h Jonathan Corbet
@ 2017-07-17 21:00 ` Jonathan Corbet
  2017-07-17 21:00 ` [PATCH 3/7] docs: Do not include from .../seqno-fence.c Jonathan Corbet
                   ` (4 subsequent siblings)
  6 siblings, 0 replies; 10+ messages in thread
From: Jonathan Corbet @ 2017-07-17 21:00 UTC (permalink / raw)
  To: linux-doc; +Cc: linux-kernel, dri-devel, Jonathan Corbet

...because there are none there, and I cannot figure out what would ever
have been of interest there.  This eliminates this warning:

    ./kernel/sys.c:1: warning: no structured comments found

from the build.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/driver-api/basics.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index cbfb5a825077..73fa7d42bbba 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -103,9 +103,6 @@ Kernel utility functions
 .. kernel-doc:: kernel/panic.c
    :export:
 
-.. kernel-doc:: kernel/sys.c
-   :export:
-
 .. kernel-doc:: kernel/rcu/tree.c
    :export:
 
-- 
2.9.4

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

^ permalink raw reply related	[flat|nested] 10+ messages in thread

* [PATCH 3/7] docs: Do not include from .../seqno-fence.c
  2017-07-17 21:00 [PATCH 0/7] Documentation warning reduction Jonathan Corbet
  2017-07-17 21:00 ` [PATCH 1/7] docs: Get module_init() docs from module.h Jonathan Corbet
  2017-07-17 21:00 ` [PATCH 2/7] docs: Do not include kerneldoc comments from kernel/sys.c Jonathan Corbet
@ 2017-07-17 21:00 ` Jonathan Corbet
  2017-07-17 21:00 ` [PATCH 4/7] docs: Get the struct cmbdata kernel doc from the right file Jonathan Corbet
                   ` (3 subsequent siblings)
  6 siblings, 0 replies; 10+ messages in thread
From: Jonathan Corbet @ 2017-07-17 21:00 UTC (permalink / raw)
  To: linux-doc; +Cc: linux-kernel, dri-devel, Jonathan Corbet

There are no kerneldoc comments in drivers/dma-buf/seqno-fence.c, and it
appears there never have been.  Stop looking for comments there to
eliminate this warning:

    ./drivers/dma-buf/seqno-fence.c:1: warning: no structured comments found

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/driver-api/dma-buf.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst
index 31671b469627..dc384f2f7f34 100644
--- a/Documentation/driver-api/dma-buf.rst
+++ b/Documentation/driver-api/dma-buf.rst
@@ -139,9 +139,6 @@ DMA Fences
 Seqno Hardware Fences
 ~~~~~~~~~~~~~~~~~~~~~
 
-.. kernel-doc:: drivers/dma-buf/seqno-fence.c
-   :export:
-
 .. kernel-doc:: include/linux/seqno-fence.h
    :internal:
 
-- 
2.9.4

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

^ permalink raw reply related	[flat|nested] 10+ messages in thread

* [PATCH 4/7] docs: Get the struct cmbdata kernel doc from the right file
  2017-07-17 21:00 [PATCH 0/7] Documentation warning reduction Jonathan Corbet
                   ` (2 preceding siblings ...)
  2017-07-17 21:00 ` [PATCH 3/7] docs: Do not include from .../seqno-fence.c Jonathan Corbet
@ 2017-07-17 21:00 ` Jonathan Corbet
  2017-07-17 21:00 ` [PATCH 5/7] docs: Do not include from drivers/scsi/constants.c Jonathan Corbet
                   ` (2 subsequent siblings)
  6 siblings, 0 replies; 10+ messages in thread
From: Jonathan Corbet @ 2017-07-17 21:00 UTC (permalink / raw)
  To: linux-doc; +Cc: linux-kernel, dri-devel, Jonathan Corbet

Back in 2012, commit 9807f75955ea (UAPI: (Scripted) Disintegrate
arch/s390/include/asm) moved struct cmbdata (and its kerneldoc comments) to
another file, but did not update the docs to match.  The result is this
warning:

    ./arch/s390/include/asm/cmb.h:1: warning: no structured comments found

...and no documentation for that structure.  Update the docs to get the
information from the right place.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/driver-api/s390-drivers.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/s390-drivers.rst b/Documentation/driver-api/s390-drivers.rst
index 7060da136095..ecf8851d3565 100644
--- a/Documentation/driver-api/s390-drivers.rst
+++ b/Documentation/driver-api/s390-drivers.rst
@@ -75,7 +75,7 @@ The channel-measurement facility provides a means to collect measurement
 data which is made available by the channel subsystem for each channel
 attached device.
 
-.. kernel-doc:: arch/s390/include/asm/cmb.h
+.. kernel-doc:: arch/s390/include/uapi/asm/cmb.h
    :internal:
 
 .. kernel-doc:: drivers/s390/cio/cmf.c
-- 
2.9.4

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

^ permalink raw reply related	[flat|nested] 10+ messages in thread

* [PATCH 5/7] docs: Do not include from drivers/scsi/constants.c
  2017-07-17 21:00 [PATCH 0/7] Documentation warning reduction Jonathan Corbet
                   ` (3 preceding siblings ...)
  2017-07-17 21:00 ` [PATCH 4/7] docs: Get the struct cmbdata kernel doc from the right file Jonathan Corbet
@ 2017-07-17 21:00 ` Jonathan Corbet
  2017-07-17 21:00 ` [PATCH 6/7] docs: Do not include from include/drm/drm_color_mgmt.h Jonathan Corbet
  2017-07-17 21:00 ` [PATCH 7/7] docs: Use :internal: for include/drm/drm_syncobj.h Jonathan Corbet
  6 siblings, 0 replies; 10+ messages in thread
From: Jonathan Corbet @ 2017-07-17 21:00 UTC (permalink / raw)
  To: linux-doc; +Cc: linux-kernel, dri-devel, Jonathan Corbet

The only function of interest in that file was scsi_print_status().  That
function was removed in commit 7ac7076344d9 (scsi: remove
scsi_print_status()) but the docs were not changed to match, yielding this
warning:

    ./drivers/scsi/constants.c:1: warning: no structured comments found

There's nothing there anymore, so just remove that section from the docs.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/driver-api/scsi.rst | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst
index 859fb672319f..5a2aa7a377d9 100644
--- a/Documentation/driver-api/scsi.rst
+++ b/Documentation/driver-api/scsi.rst
@@ -224,14 +224,6 @@ mid to lowlevel SCSI driver interface
 .. kernel-doc:: drivers/scsi/hosts.c
    :export:
 
-drivers/scsi/constants.c
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-mid to lowlevel SCSI driver interface
-
-.. kernel-doc:: drivers/scsi/constants.c
-   :export:
-
 Transport classes
 -----------------
 
-- 
2.9.4


^ permalink raw reply related	[flat|nested] 10+ messages in thread

* [PATCH 6/7] docs: Do not include from include/drm/drm_color_mgmt.h
  2017-07-17 21:00 [PATCH 0/7] Documentation warning reduction Jonathan Corbet
                   ` (4 preceding siblings ...)
  2017-07-17 21:00 ` [PATCH 5/7] docs: Do not include from drivers/scsi/constants.c Jonathan Corbet
@ 2017-07-17 21:00 ` Jonathan Corbet
  2017-07-18  6:42   ` Daniel Vetter
  2017-07-17 21:00 ` [PATCH 7/7] docs: Use :internal: for include/drm/drm_syncobj.h Jonathan Corbet
  6 siblings, 1 reply; 10+ messages in thread
From: Jonathan Corbet @ 2017-07-17 21:00 UTC (permalink / raw)
  To: linux-doc; +Cc: linux-kernel, dri-devel, Jonathan Corbet

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

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

^ permalink raw reply related	[flat|nested] 10+ messages in thread

* [PATCH 7/7] docs: Use :internal: for include/drm/drm_syncobj.h
  2017-07-17 21:00 [PATCH 0/7] Documentation warning reduction Jonathan Corbet
                   ` (5 preceding siblings ...)
  2017-07-17 21:00 ` [PATCH 6/7] docs: Do not include from include/drm/drm_color_mgmt.h Jonathan Corbet
@ 2017-07-17 21:00 ` Jonathan Corbet
  6 siblings, 0 replies; 10+ messages in thread
From: Jonathan Corbet @ 2017-07-17 21:00 UTC (permalink / raw)
  To: linux-doc; +Cc: linux-kernel, dri-devel, Jonathan Corbet

Documentation/gpu/drm-mm.rst includes from include/drm/drm_syncobj.h with
:export:, but this is a header file without export directives.  That
results in this warning:

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

...and a failure to obtain the documentation from that file.  Switch to
:internal: instead to make both problems go away.

Cc: dri-devel@lists.freedesktop.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/gpu/drm-mm.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
index 9412798645c1..300898298bf6 100644
--- a/Documentation/gpu/drm-mm.rst
+++ b/Documentation/gpu/drm-mm.rst
@@ -492,7 +492,7 @@ DRM Sync Objects
    :doc: Overview
 
 .. kernel-doc:: include/drm/drm_syncobj.h
-   :export:
+   :internal:
 
 .. kernel-doc:: drivers/gpu/drm/drm_syncobj.c
    :export:
-- 
2.9.4

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

^ permalink raw reply related	[flat|nested] 10+ messages in thread

* Re: [PATCH 6/7] docs: Do not include from include/drm/drm_color_mgmt.h
  2017-07-17 21:00 ` [PATCH 6/7] docs: Do not include from include/drm/drm_color_mgmt.h Jonathan Corbet
@ 2017-07-18  6:42   ` Daniel Vetter
  2017-07-18 13:09     ` Jonathan Corbet
  0 siblings, 1 reply; 10+ messages in thread
From: Daniel Vetter @ 2017-07-18  6:42 UTC (permalink / raw)
  To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, dri-devel

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

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH 6/7] docs: Do not include from include/drm/drm_color_mgmt.h
  2017-07-18  6:42   ` Daniel Vetter
@ 2017-07-18 13:09     ` Jonathan Corbet
  0 siblings, 0 replies; 10+ messages in thread
From: Jonathan Corbet @ 2017-07-18 13:09 UTC (permalink / raw)
  To: Daniel Vetter; +Cc: linux-doc, linux-kernel, dri-devel

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

^ permalink raw reply	[flat|nested] 10+ messages in thread

end of thread, other threads:[~2017-07-18 13:09 UTC | newest]

Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-07-17 21:00 [PATCH 0/7] Documentation warning reduction Jonathan Corbet
2017-07-17 21:00 ` [PATCH 1/7] docs: Get module_init() docs from module.h Jonathan Corbet
2017-07-17 21:00 ` [PATCH 2/7] docs: Do not include kerneldoc comments from kernel/sys.c Jonathan Corbet
2017-07-17 21:00 ` [PATCH 3/7] docs: Do not include from .../seqno-fence.c Jonathan Corbet
2017-07-17 21:00 ` [PATCH 4/7] docs: Get the struct cmbdata kernel doc from the right file Jonathan Corbet
2017-07-17 21:00 ` [PATCH 5/7] docs: Do not include from drivers/scsi/constants.c Jonathan Corbet
2017-07-17 21:00 ` [PATCH 6/7] docs: Do not include from include/drm/drm_color_mgmt.h Jonathan Corbet
2017-07-18  6:42   ` Daniel Vetter
2017-07-18 13:09     ` Jonathan Corbet
2017-07-17 21:00 ` [PATCH 7/7] docs: Use :internal: for include/drm/drm_syncobj.h Jonathan Corbet

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).