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
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: [email protected]
Signed-off-by: Jonathan Corbet <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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: [email protected]
Signed-off-by: Jonathan Corbet <[email protected]>
---
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
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 <[email protected]>
---
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
...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 <[email protected]>
---
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
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: [email protected]
> Signed-off-by: Jonathan Corbet <[email protected]>
> ---
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 <[email protected]>
> 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 [email protected]
> 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 <[email protected]> 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: [email protected]
> > Signed-off-by: Jonathan Corbet <[email protected]>
> > ---
>
> 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