[PATCH 0/6] Add support for in-line nested struct comments

[PATCH 0/6] Add support for in-line nested struct comments

[Mauro Carvalho Chehab]

This series fix two bugs at kernel-doc.rst examples and add support
for in-line nested struct comments.

It also converts one documentation at intel_dpio_phy to use it,
in order to give a practical example about how to use it.

Mauro Carvalho Chehab (6):
  doc-guide: kernel-doc: fix example for nested_foobar struct
  doc-guide: kernel-doc: fix example for inlined comments
  doc-guide: kernel-doc: move in-line section to be after nested struct
  scripts: kernel-doc: support in-line comments on nested structs/unions
  doc-guide: kernel-doc: add examples about nested union/structs
  drm: intel_dpio_phy: fix kernel-doc comments at nested struct

 Documentation/doc-guide/kernel-doc.rst | 69 ++++++++++++++++++++--------------
 drivers/gpu/drm/i915/intel_dpio_phy.c  |  2 +-
 scripts/kernel-doc                     |  2 +-
 3 files changed, 43 insertions(+), 30 deletions(-)

-- 
2.14.3


_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

[PATCH 6/6] drm: intel_dpio_phy: fix kernel-doc comments at nested struct

[Mauro Carvalho Chehab]

The in-lined comments for channel.port doesn't follow the syntax
described at kernel-doc document, causing the following warning:

	$ ./scripts/kernel-doc -none drivers/gpu/drm/i915/intel_dpio_phy.c
	drivers/gpu/drm/i915/intel_dpio_phy.c:154: warning: Function parameter or member 'channel.port' not described in 'bxt_ddi_phy_info'

While the best would be for the Kernel to deduce that from the
context, supporting it is not trivial. So, let's just stick with
the existing syntax.

Reported-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 drivers/gpu/drm/i915/intel_dpio_phy.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/intel_dpio_phy.c b/drivers/gpu/drm/i915/intel_dpio_phy.c
index 76473e9836c6..c8e9e44e5981 100644
--- a/drivers/gpu/drm/i915/intel_dpio_phy.c
+++ b/drivers/gpu/drm/i915/intel_dpio_phy.c
@@ -147,7 +147,7 @@ struct bxt_ddi_phy_info {
 	 */
 	struct {
 		/**
-		 * @port: which port maps to this channel.
+		 * @channel.port: which port maps to this channel.
 		 */
 		enum port port;
 	} channel[2];
-- 
2.14.3

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH 0/6] Add support for in-line nested struct comments

[Jonathan Corbet]

On Fri, 16 Feb 2018 11:48:14 -0200
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> his series fix two bugs at kernel-doc.rst examples and add support
> for in-line nested struct comments.
> 
> It also converts one documentation at intel_dpio_phy to use it,
> in order to give a practical example about how to use it.

OK, I've applied everything but the last patch, which I assume will go
through the DRM tree.

Thanks,

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

Re: [PATCH 0/6] Add support for in-line nested struct comments

[Jani Nikula]

On Sun, 18 Feb 2018, Jonathan Corbet <corbet@lwn.net> wrote:
> On Fri, 16 Feb 2018 11:48:14 -0200
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
>
>> his series fix two bugs at kernel-doc.rst examples and add support
>> for in-line nested struct comments.
>> 
>> It also converts one documentation at intel_dpio_phy to use it,
>> in order to give a practical example about how to use it.
>
> OK, I've applied everything but the last patch, which I assume will go
> through the DRM tree.

I was going to reference the kernel-doc commit while applying patch 6,
but I can't find the others. I guess applied literally meant just
applied, not pushed... ;)

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 0/6] Add support for in-line nested struct comments

[Daniel Vetter]

On Fri, Feb 16, 2018 at 11:48:14AM -0200, Mauro Carvalho Chehab wrote:
> This series fix two bugs at kernel-doc.rst examples and add support
> for in-line nested struct comments.
> 
> It also converts one documentation at intel_dpio_phy to use it,
> in order to give a practical example about how to use it.
> 
> Mauro Carvalho Chehab (6):
>   doc-guide: kernel-doc: fix example for nested_foobar struct
>   doc-guide: kernel-doc: fix example for inlined comments
>   doc-guide: kernel-doc: move in-line section to be after nested struct
>   scripts: kernel-doc: support in-line comments on nested structs/unions
>   doc-guide: kernel-doc: add examples about nested union/structs
>   drm: intel_dpio_phy: fix kernel-doc comments at nested struct

Oh, this is cool. Thanks a lot for doing this.
-Daniel

> 
>  Documentation/doc-guide/kernel-doc.rst | 69 ++++++++++++++++++++--------------
>  drivers/gpu/drm/i915/intel_dpio_phy.c  |  2 +-
>  scripts/kernel-doc                     |  2 +-
>  3 files changed, 43 insertions(+), 30 deletions(-)
> 
> -- 
> 2.14.3
> 
> 
> _______________________________________________
> Intel-gfx mailing list
> Intel-gfx@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/intel-gfx

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx