[PATCH 0/3] Fix Kernel-doc warnings introduced on next-20200921

[PATCH 0/3] Fix Kernel-doc warnings introduced on next-20200921

[Mauro Carvalho Chehab]

A few new warnings were added at linux-next. Address them, in order for us
to keep zero warnings at the docs.

The entire patchset fixing all kernel-doc warnings is at:
	https://git.linuxtv.org/mchehab/experimental.git/log/?h=doc-fixes

Mauro Carvalho Chehab (3):
  net: fix a new kernel-doc warning at dev.c
  drm/dp: fix kernel-doc warnings at drm_dp_helper.c
  drm/dp: fix a kernel-doc issue at drm_edid.c

 drivers/gpu/drm/drm_dp_helper.c | 5 +++++
 drivers/gpu/drm/drm_edid.c      | 2 +-
 net/core/dev.c                  | 4 ++--
 3 files changed, 8 insertions(+), 3 deletions(-)

-- 
2.26.2

[PATCH 0/3] Fix Kernel-doc warnings introduced on next-20200921

[Mauro Carvalho Chehab]

A few new warnings were added at linux-next. Address them, in order for us
to keep zero warnings at the docs.

The entire patchset fixing all kernel-doc warnings is at:
	https://git.linuxtv.org/mchehab/experimental.git/log/?h=doc-fixes

Mauro Carvalho Chehab (3):
  net: fix a new kernel-doc warning at dev.c
  drm/dp: fix kernel-doc warnings at drm_dp_helper.c
  drm/dp: fix a kernel-doc issue at drm_edid.c

 drivers/gpu/drm/drm_dp_helper.c | 5 +++++
 drivers/gpu/drm/drm_edid.c      | 2 +-
 net/core/dev.c                  | 4 ++--
 3 files changed, 8 insertions(+), 3 deletions(-)

-- 
2.26.2


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

[PATCH 1/3] net: fix a new kernel-doc warning at dev.c

[Mauro Carvalho Chehab]

kernel-doc expects the function prototype to be just after
the kernel-doc markup, as otherwise it will get it all wrong:

	./net/core/dev.c:10036: warning: Excess function parameter 'dev' description in 'WAIT_REFS_MIN_MSECS'

Fixes: 0e4be9e57e8c ("net: use exponential backoff in netdev_wait_allrefs")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 net/core/dev.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/net/core/dev.c b/net/core/dev.c
index a268ff35ad38..873b50ac9668 100644
--- a/net/core/dev.c
+++ b/net/core/dev.c
@@ -10021,6 +10021,8 @@ int netdev_refcnt_read(const struct net_device *dev)
 }
 EXPORT_SYMBOL(netdev_refcnt_read);
 
+#define WAIT_REFS_MIN_MSECS 1
+#define WAIT_REFS_MAX_MSECS 250
 /**
  * netdev_wait_allrefs - wait until all references are gone.
  * @dev: target net_device
@@ -10033,8 +10035,6 @@ EXPORT_SYMBOL(netdev_refcnt_read);
  * We can get stuck here if buggy protocols don't correctly
  * call dev_put.
  */
-#define WAIT_REFS_MIN_MSECS 1
-#define WAIT_REFS_MAX_MSECS 250
 static void netdev_wait_allrefs(struct net_device *dev)
 {
 	unsigned long rebroadcast_time, warning_time;
-- 
2.26.2

[PATCH 2/3] drm/dp: fix kernel-doc warnings at drm_dp_helper.c

[Mauro Carvalho Chehab]

As warned by kernel-doc:

	./drivers/gpu/drm/drm_dp_helper.c:385: warning: Function parameter or member 'type' not described in 'drm_dp_downstream_is_type'
	./drivers/gpu/drm/drm_dp_helper.c:886: warning: Function parameter or member 'dev' not described in 'drm_dp_downstream_mode'

Some function parameters weren't documented.

Fixes: 38784f6f8805 ("drm/dp: Add helpers to identify downstream facing port types")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpu/drm/drm_dp_helper.c | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
index b1c71af88579..deeed73f4ed6 100644
--- a/drivers/gpu/drm/drm_dp_helper.c
+++ b/drivers/gpu/drm/drm_dp_helper.c
@@ -374,6 +374,10 @@ static bool is_edid_digital_input_dp(const struct edid *edid)
  * drm_dp_downstream_is_type() - is the downstream facing port of certain type?
  * @dpcd: DisplayPort configuration data
  * @port_cap: port capabilities
+ * @type: port type to be checked. Can be:
+ * 	  %DP_DS_PORT_TYPE_DP, %DP_DS_PORT_TYPE_VGA, %DP_DS_PORT_TYPE_DVI,
+ * 	  %DP_DS_PORT_TYPE_HDMI, %DP_DS_PORT_TYPE_NON_EDID,
+ *	  %DP_DS_PORT_TYPE_DP_DUALMODE or %DP_DS_PORT_TYPE_WIRELESS.
  *
  * Caveat: Only works with DPCD 1.1+ port caps.
  *
@@ -870,6 +874,7 @@ EXPORT_SYMBOL(drm_dp_downstream_444_to_420_conversion);
 
 /**
  * drm_dp_downstream_mode() - return a mode for downstream facing port
+ * @dev: DRM device
  * @dpcd: DisplayPort configuration data
  * @port_cap: port capabilities
  *
-- 
2.26.2

[PATCH 2/3] drm/dp: fix kernel-doc warnings at drm_dp_helper.c

[Mauro Carvalho Chehab]

As warned by kernel-doc:

	./drivers/gpu/drm/drm_dp_helper.c:385: warning: Function parameter or member 'type' not described in 'drm_dp_downstream_is_type'
	./drivers/gpu/drm/drm_dp_helper.c:886: warning: Function parameter or member 'dev' not described in 'drm_dp_downstream_mode'

Some function parameters weren't documented.

Fixes: 38784f6f8805 ("drm/dp: Add helpers to identify downstream facing port types")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpu/drm/drm_dp_helper.c | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
index b1c71af88579..deeed73f4ed6 100644
--- a/drivers/gpu/drm/drm_dp_helper.c
+++ b/drivers/gpu/drm/drm_dp_helper.c
@@ -374,6 +374,10 @@ static bool is_edid_digital_input_dp(const struct edid *edid)
  * drm_dp_downstream_is_type() - is the downstream facing port of certain type?
  * @dpcd: DisplayPort configuration data
  * @port_cap: port capabilities
+ * @type: port type to be checked. Can be:
+ * 	  %DP_DS_PORT_TYPE_DP, %DP_DS_PORT_TYPE_VGA, %DP_DS_PORT_TYPE_DVI,
+ * 	  %DP_DS_PORT_TYPE_HDMI, %DP_DS_PORT_TYPE_NON_EDID,
+ *	  %DP_DS_PORT_TYPE_DP_DUALMODE or %DP_DS_PORT_TYPE_WIRELESS.
  *
  * Caveat: Only works with DPCD 1.1+ port caps.
  *
@@ -870,6 +874,7 @@ EXPORT_SYMBOL(drm_dp_downstream_444_to_420_conversion);
 
 /**
  * drm_dp_downstream_mode() - return a mode for downstream facing port
+ * @dev: DRM device
  * @dpcd: DisplayPort configuration data
  * @port_cap: port capabilities
  *
-- 
2.26.2

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

[PATCH 3/3] drm/dp: fix a kernel-doc issue at drm_edid.c

[Mauro Carvalho Chehab]

The name of the argument is different, causing those warnings:

	./drivers/gpu/drm/drm_edid.c:3754: warning: Function parameter or member 'video_code' not described in 'drm_display_mode_from_cea_vic'
	./drivers/gpu/drm/drm_edid.c:3754: warning: Excess function parameter 'vic' description in 'drm_display_mode_from_cea_vic'

Fixes: 7af655bce275 ("drm/dp: Add drm_dp_downstream_mode()")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpu/drm/drm_edid.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/drm_edid.c b/drivers/gpu/drm/drm_edid.c
index a82f37d44258..631125b46e04 100644
--- a/drivers/gpu/drm/drm_edid.c
+++ b/drivers/gpu/drm/drm_edid.c
@@ -3741,7 +3741,7 @@ drm_add_cmdb_modes(struct drm_connector *connector, u8 svd)
 /**
  * drm_display_mode_from_cea_vic() - return a mode for CEA VIC
  * @dev: DRM device
- * @vic: CEA VIC of the mode
+ * @video_code: CEA VIC of the mode
  *
  * Creates a new mode matching the specified CEA VIC.
  *
-- 
2.26.2

[PATCH 3/3] drm/dp: fix a kernel-doc issue at drm_edid.c

[Mauro Carvalho Chehab]

The name of the argument is different, causing those warnings:

	./drivers/gpu/drm/drm_edid.c:3754: warning: Function parameter or member 'video_code' not described in 'drm_display_mode_from_cea_vic'
	./drivers/gpu/drm/drm_edid.c:3754: warning: Excess function parameter 'vic' description in 'drm_display_mode_from_cea_vic'

Fixes: 7af655bce275 ("drm/dp: Add drm_dp_downstream_mode()")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpu/drm/drm_edid.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/drm_edid.c b/drivers/gpu/drm/drm_edid.c
index a82f37d44258..631125b46e04 100644
--- a/drivers/gpu/drm/drm_edid.c
+++ b/drivers/gpu/drm/drm_edid.c
@@ -3741,7 +3741,7 @@ drm_add_cmdb_modes(struct drm_connector *connector, u8 svd)
 /**
  * drm_display_mode_from_cea_vic() - return a mode for CEA VIC
  * @dev: DRM device
- * @vic: CEA VIC of the mode
+ * @video_code: CEA VIC of the mode
  *
  * Creates a new mode matching the specified CEA VIC.
  *
-- 
2.26.2

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

Re: [PATCH 0/3] Fix Kernel-doc warnings introduced on next-20200921

[Lyude Paul]

For patches 2 and 3:

Reviewed-by: Lyude Paul <lyude@redhat.com>

I'll go ahead and push these to drm-intel-next-queued (since drm-misc-next
doesn't have these patches in yet, and the commits these fix were originally
merged through drm-intel-next-queued anyway). thanks!

On Tue, 2020-09-22 at 13:22 +0200, Mauro Carvalho Chehab wrote:
> A few new warnings were added at linux-next. Address them, in order for us
> to keep zero warnings at the docs.
> 
> The entire patchset fixing all kernel-doc warnings is at:
> 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=doc-fixes
> 
> Mauro Carvalho Chehab (3):
>   net: fix a new kernel-doc warning at dev.c
>   drm/dp: fix kernel-doc warnings at drm_dp_helper.c
>   drm/dp: fix a kernel-doc issue at drm_edid.c
> 
>  drivers/gpu/drm/drm_dp_helper.c | 5 +++++
>  drivers/gpu/drm/drm_edid.c      | 2 +-
>  net/core/dev.c                  | 4 ++--
>  3 files changed, 8 insertions(+), 3 deletions(-)
> 
-- 
Cheers,
	Lyude Paul (she/her)
	Software Engineer at Red Hat

Re: [PATCH 0/3] Fix Kernel-doc warnings introduced on next-20200921

[Lyude Paul]

For patches 2 and 3:

Reviewed-by: Lyude Paul <lyude@redhat.com>

I'll go ahead and push these to drm-intel-next-queued (since drm-misc-next
doesn't have these patches in yet, and the commits these fix were originally
merged through drm-intel-next-queued anyway). thanks!

On Tue, 2020-09-22 at 13:22 +0200, Mauro Carvalho Chehab wrote:
> A few new warnings were added at linux-next. Address them, in order for us
> to keep zero warnings at the docs.
> 
> The entire patchset fixing all kernel-doc warnings is at:
> 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=doc-fixes
> 
> Mauro Carvalho Chehab (3):
>   net: fix a new kernel-doc warning at dev.c
>   drm/dp: fix kernel-doc warnings at drm_dp_helper.c
>   drm/dp: fix a kernel-doc issue at drm_edid.c
> 
>  drivers/gpu/drm/drm_dp_helper.c | 5 +++++
>  drivers/gpu/drm/drm_edid.c      | 2 +-
>  net/core/dev.c                  | 4 ++--
>  3 files changed, 8 insertions(+), 3 deletions(-)
> 
-- 
Cheers,
	Lyude Paul (she/her)
	Software Engineer at Red Hat

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

Re: [PATCH 1/3] net: fix a new kernel-doc warning at dev.c

[Francesco Ruggeri]

On Tue, Sep 22, 2020 at 4:22 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> kernel-doc expects the function prototype to be just after
> the kernel-doc markup, as otherwise it will get it all wrong:
>
>         ./net/core/dev.c:10036: warning: Excess function parameter 'dev' description in 'WAIT_REFS_MIN_MSECS'
>
> Fixes: 0e4be9e57e8c ("net: use exponential backoff in netdev_wait_allrefs")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  net/core/dev.c | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/net/core/dev.c b/net/core/dev.c
> index a268ff35ad38..873b50ac9668 100644
> --- a/net/core/dev.c
> +++ b/net/core/dev.c
> @@ -10021,6 +10021,8 @@ int netdev_refcnt_read(const struct net_device *dev)
>  }
>  EXPORT_SYMBOL(netdev_refcnt_read);
>
> +#define WAIT_REFS_MIN_MSECS 1
> +#define WAIT_REFS_MAX_MSECS 250
>  /**
>   * netdev_wait_allrefs - wait until all references are gone.
>   * @dev: target net_device
> @@ -10033,8 +10035,6 @@ EXPORT_SYMBOL(netdev_refcnt_read);
>   * We can get stuck here if buggy protocols don't correctly
>   * call dev_put.
>   */
> -#define WAIT_REFS_MIN_MSECS 1
> -#define WAIT_REFS_MAX_MSECS 250
>  static void netdev_wait_allrefs(struct net_device *dev)
>  {
>         unsigned long rebroadcast_time, warning_time;
> --
> 2.26.2
>

Re: [PATCH 1/3] net: fix a new kernel-doc warning at dev.c

[Francesco Ruggeri]

On Tue, Sep 22, 2020 at 4:22 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> kernel-doc expects the function prototype to be just after
> the kernel-doc markup, as otherwise it will get it all wrong:
>
>         ./net/core/dev.c:10036: warning: Excess function parameter 'dev' description in 'WAIT_REFS_MIN_MSECS'
>
> Fixes: 0e4be9e57e8c ("net: use exponential backoff in netdev_wait_allrefs")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Reviewed-by: Francesco Ruggeri <fruggeri@arista.com>

Thanks for fixing this!

Re: [PATCH 0/3] Fix Kernel-doc warnings introduced on next-20200921

[Ville Syrjälä]

On Tue, Sep 22, 2020 at 01:39:41PM -0400, Lyude Paul wrote:
> For patches 2 and 3:
> 
> Reviewed-by: Lyude Paul <lyude@redhat.com>
> 
> I'll go ahead and push these to drm-intel-next-queued (since drm-misc-next
> doesn't have these patches in yet, and the commits these fix were originally
> merged through drm-intel-next-queued anyway). thanks!

Mea culpa. My doc test build was foiled by the sphinx 2 vs. 3
regression and I was too lazy to start downgrading things.
Any ETA for getting that fixed btw?

> 
> On Tue, 2020-09-22 at 13:22 +0200, Mauro Carvalho Chehab wrote:
> > A few new warnings were added at linux-next. Address them, in order for us
> > to keep zero warnings at the docs.
> > 
> > The entire patchset fixing all kernel-doc warnings is at:
> > 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=doc-fixes
> > 
> > Mauro Carvalho Chehab (3):
> >   net: fix a new kernel-doc warning at dev.c
> >   drm/dp: fix kernel-doc warnings at drm_dp_helper.c
> >   drm/dp: fix a kernel-doc issue at drm_edid.c
> > 
> >  drivers/gpu/drm/drm_dp_helper.c | 5 +++++
> >  drivers/gpu/drm/drm_edid.c      | 2 +-
> >  net/core/dev.c                  | 4 ++--
> >  3 files changed, 8 insertions(+), 3 deletions(-)
> > 
> -- 
> Cheers,
> 	Lyude Paul (she/her)
> 	Software Engineer at Red Hat

-- 
Ville Syrjälä
Intel

Re: [PATCH 0/3] Fix Kernel-doc warnings introduced on next-20200921

[Ville Syrjälä]

On Tue, Sep 22, 2020 at 01:39:41PM -0400, Lyude Paul wrote:
> For patches 2 and 3:
> 
> Reviewed-by: Lyude Paul <lyude@redhat.com>
> 
> I'll go ahead and push these to drm-intel-next-queued (since drm-misc-next
> doesn't have these patches in yet, and the commits these fix were originally
> merged through drm-intel-next-queued anyway). thanks!

Mea culpa. My doc test build was foiled by the sphinx 2 vs. 3
regression and I was too lazy to start downgrading things.
Any ETA for getting that fixed btw?

> 
> On Tue, 2020-09-22 at 13:22 +0200, Mauro Carvalho Chehab wrote:
> > A few new warnings were added at linux-next. Address them, in order for us
> > to keep zero warnings at the docs.
> > 
> > The entire patchset fixing all kernel-doc warnings is at:
> > 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=doc-fixes
> > 
> > Mauro Carvalho Chehab (3):
> >   net: fix a new kernel-doc warning at dev.c
> >   drm/dp: fix kernel-doc warnings at drm_dp_helper.c
> >   drm/dp: fix a kernel-doc issue at drm_edid.c
> > 
> >  drivers/gpu/drm/drm_dp_helper.c | 5 +++++
> >  drivers/gpu/drm/drm_edid.c      | 2 +-
> >  net/core/dev.c                  | 4 ++--
> >  3 files changed, 8 insertions(+), 3 deletions(-)
> > 
> -- 
> Cheers,
> 	Lyude Paul (she/her)
> 	Software Engineer at Red Hat

-- 
Ville Syrjälä
Intel
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 0/3] Fix Kernel-doc warnings introduced on next-20200921

[Jonathan Corbet]

On Tue, 22 Sep 2020 20:52:06 +0300
Ville Syrjälä <ville.syrjala@linux.intel.com> wrote:

> Mea culpa. My doc test build was foiled by the sphinx 2 vs. 3
> regression and I was too lazy to start downgrading things.
> Any ETA for getting that fixed btw?

There's a fix of sorts in docs-next (and thus linux-next) now, has been
there for a few weeks.  Really fixing that problem properly requires more
time than anybody seems to have at the moment.

jon

Re: [PATCH 0/3] Fix Kernel-doc warnings introduced on next-20200921

[Jonathan Corbet]

On Tue, 22 Sep 2020 20:52:06 +0300
Ville Syrjälä <ville.syrjala@linux.intel.com> wrote:

> Mea culpa. My doc test build was foiled by the sphinx 2 vs. 3
> regression and I was too lazy to start downgrading things.
> Any ETA for getting that fixed btw?

There's a fix of sorts in docs-next (and thus linux-next) now, has been
there for a few weeks.  Really fixing that problem properly requires more
time than anybody seems to have at the moment.

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

Re: [PATCH 1/3] net: fix a new kernel-doc warning at dev.c

[David Miller]

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: Tue, 22 Sep 2020 13:22:52 +0200

> kernel-doc expects the function prototype to be just after
> the kernel-doc markup, as otherwise it will get it all wrong:
> 
> 	./net/core/dev.c:10036: warning: Excess function parameter 'dev' description in 'WAIT_REFS_MIN_MSECS'
> 
> Fixes: 0e4be9e57e8c ("net: use exponential backoff in netdev_wait_allrefs")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Applied to net-next.