[02/11] drm/doc: Add kerneldoc for @index
diff mbox

Message ID 1468612088-9721-2-git-send-email-daniel.vetter@ffwll.ch
State New
Headers show

Commit Message

Daniel Vetter July 15, 2016, 7:47 p.m. UTC
Was forgotten when adding them all over. 0-day should complain about
new missing kernel-doc, not sure why that wasn't caught/fixed.

Cc: Chris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 include/drm/drm_crtc.h | 26 +++++++++++++++++++++-----
 1 file changed, 21 insertions(+), 5 deletions(-)

Comments

Chris Wilson July 15, 2016, 8:06 p.m. UTC | #1
On Fri, Jul 15, 2016 at 09:47:59PM +0200, Daniel Vetter wrote:
> Was forgotten when adding them all over. 0-day should complain about
> new missing kernel-doc, not sure why that wasn't caught/fixed.
> 
> Cc: Chris Wilson <chris@chris-wilson.co.uk>
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> ---
>  include/drm/drm_crtc.h | 26 +++++++++++++++++++++-----
>  1 file changed, 21 insertions(+), 5 deletions(-)
> 
> diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
> index ebf078685f86..656f189f1198 100644
> --- a/include/drm/drm_crtc.h
> +++ b/include/drm/drm_crtc.h
> @@ -783,7 +783,10 @@ struct drm_crtc {
>  	struct drm_plane *primary;
>  	struct drm_plane *cursor;
>  
> -	/* position inside the mode_config.list, can be used as a [] idx */
> +	/**
> +	 * @index: Position inside the mode_config.list, can be used as an array

For all:

@index: Fixed position inside the mode_config.list, can be used as an
array index. The @index is assigned when the crtc is inserted into the
list, and it will remain at that position inside the list until the
module is unloaded.

Just want to emphasis the unchanging nature of the @index. Second
sentence may be overkill.
-Chris
Daniel Vetter July 18, 2016, 7:15 a.m. UTC | #2
On Fri, Jul 15, 2016 at 09:06:04PM +0100, Chris Wilson wrote:
> On Fri, Jul 15, 2016 at 09:47:59PM +0200, Daniel Vetter wrote:
> > Was forgotten when adding them all over. 0-day should complain about
> > new missing kernel-doc, not sure why that wasn't caught/fixed.
> > 
> > Cc: Chris Wilson <chris@chris-wilson.co.uk>
> > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> > ---
> >  include/drm/drm_crtc.h | 26 +++++++++++++++++++++-----
> >  1 file changed, 21 insertions(+), 5 deletions(-)
> > 
> > diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
> > index ebf078685f86..656f189f1198 100644
> > --- a/include/drm/drm_crtc.h
> > +++ b/include/drm/drm_crtc.h
> > @@ -783,7 +783,10 @@ struct drm_crtc {
> >  	struct drm_plane *primary;
> >  	struct drm_plane *cursor;
> >  
> > -	/* position inside the mode_config.list, can be used as a [] idx */
> > +	/**
> > +	 * @index: Position inside the mode_config.list, can be used as an array
> 
> For all:
> 
> @index: Fixed position inside the mode_config.list, can be used as an
> array index. The @index is assigned when the crtc is inserted into the
> list, and it will remain at that position inside the list until the
> module is unloaded.
> 
> Just want to emphasis the unchanging nature of the @index. Second
> sentence may be overkill.

Just adding "It is invariant over the lifetime of $object." for brevity?
-Daniel
Chris Wilson July 18, 2016, 7:29 a.m. UTC | #3
On Mon, Jul 18, 2016 at 09:15:35AM +0200, Daniel Vetter wrote:
> On Fri, Jul 15, 2016 at 09:06:04PM +0100, Chris Wilson wrote:
> > On Fri, Jul 15, 2016 at 09:47:59PM +0200, Daniel Vetter wrote:
> > > Was forgotten when adding them all over. 0-day should complain about
> > > new missing kernel-doc, not sure why that wasn't caught/fixed.
> > > 
> > > Cc: Chris Wilson <chris@chris-wilson.co.uk>
> > > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> > > ---
> > >  include/drm/drm_crtc.h | 26 +++++++++++++++++++++-----
> > >  1 file changed, 21 insertions(+), 5 deletions(-)
> > > 
> > > diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
> > > index ebf078685f86..656f189f1198 100644
> > > --- a/include/drm/drm_crtc.h
> > > +++ b/include/drm/drm_crtc.h
> > > @@ -783,7 +783,10 @@ struct drm_crtc {
> > >  	struct drm_plane *primary;
> > >  	struct drm_plane *cursor;
> > >  
> > > -	/* position inside the mode_config.list, can be used as a [] idx */
> > > +	/**
> > > +	 * @index: Position inside the mode_config.list, can be used as an array
> > 
> > For all:
> > 
> > @index: Fixed position inside the mode_config.list, can be used as an
> > array index. The @index is assigned when the crtc is inserted into the
> > list, and it will remain at that position inside the list until the
> > module is unloaded.
> > 
> > Just want to emphasis the unchanging nature of the @index. Second
> > sentence may be overkill.
> 
> Just adding "It is invariant over the lifetime of $object." for brevity?

Wins.
-Chris

Patch
diff mbox

diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
index ebf078685f86..656f189f1198 100644
--- a/include/drm/drm_crtc.h
+++ b/include/drm/drm_crtc.h
@@ -783,7 +783,10 @@  struct drm_crtc {
 	struct drm_plane *primary;
 	struct drm_plane *cursor;
 
-	/* position inside the mode_config.list, can be used as a [] idx */
+	/**
+	 * @index: Position inside the mode_config.list, can be used as an array
+	 * index.
+	 */
 	unsigned index;
 
 	/* position of cursor plane on crtc */
@@ -1210,7 +1213,10 @@  struct drm_encoder {
 	char *name;
 	int encoder_type;
 
-	/* position inside the mode_config.list, can be used as a [] idx */
+	/**
+	 * @index: Position inside the mode_config.list, can be used as an array
+	 * index.
+	 */
 	unsigned index;
 
 	uint32_t possible_crtcs;
@@ -1713,7 +1719,10 @@  struct drm_plane {
 
 	enum drm_plane_type type;
 
-	/* position inside the mode_config.list, can be used as a [] idx */
+	/**
+	 * @index: Position inside the mode_config.list, can be used as an array
+	 * index.
+	 */
 	unsigned index;
 
 	const struct drm_plane_helper_funcs *helper_private;
@@ -2321,8 +2330,6 @@  struct drm_mode_config_funcs {
  * @fb_lock: mutex to protect fb state and lists
  * @num_fb: number of fbs available
  * @fb_list: list of framebuffers available
- * @num_connector: number of connectors on this device
- * @connector_list: list of connector objects
  * @num_encoder: number of encoders on this device
  * @encoder_list: list of encoder objects
  * @num_overlay_plane: number of overlay planes on this device
@@ -2397,8 +2404,17 @@  struct drm_mode_config {
 	int num_fb;
 	struct list_head fb_list;
 
+	/**
+	 * @num_connector: Number of connectors on this device.
+	 */
 	int num_connector;
+	/**
+	 * @connector_ida: ID allocator for connector indices.
+	 */
 	struct ida connector_ida;
+	/**
+	 * @connector_list: List of connector objects.
+	 */
 	struct list_head connector_list;
 
 	/**