[PATCH v2 4/4] drm/plane: add inline doc for struct drm_plane

[Daniel Vetter]

On Mon, Nov 07, 2016 at 07:03:33PM +0900, Gustavo Padovan wrote:
> From: Gustavo Padovan <gustavo.padovan at collabora.co.uk>
> 
> Some of the members of struct drm_plane had extra comments so for these
> add inline kernel comment to consolidate all documentation in one place.
> 
> Signed-off-by: Gustavo Padovan <gustavo.padovan at collabora.co.uk>

For in-line kerneldoc I think we want real paragraphs with real sentences,
just looks better. I bikesheded your patch to suit and applied the entire
series to drm-misc.

Thanks, Daniel

> ---
>  include/drm/drm_plane.h | 61 +++++++++++++++++++++++++++++++++++++++----------
>  1 file changed, 49 insertions(+), 12 deletions(-)
> 
> diff --git a/include/drm/drm_plane.h b/include/drm/drm_plane.h
> index 68f6d22..683b170 100644
> --- a/include/drm/drm_plane.h
> +++ b/include/drm/drm_plane.h
> @@ -32,11 +32,6 @@ struct drm_crtc;
>  /**
>   * struct drm_plane_state - mutable plane state
>   * @plane: backpointer to the plane
> - * @crtc: currently bound CRTC, NULL if disabled
> - * @fb: currently bound framebuffer
> - * @fence: optional fence to wait for before scanning out @fb
> - * @crtc_x: left position of visible portion of plane on crtc
> - * @crtc_y: upper position of visible portion of plane on crtc
>   * @crtc_w: width of visible portion of plane on crtc
>   * @crtc_h: height of visible portion of plane on crtc
>   * @src_x: left position of visible portion of plane within
> @@ -51,18 +46,56 @@ struct drm_crtc;
>   *	where N is the number of active planes for given crtc
>   * @src: clipped source coordinates of the plane (in 16.16)
>   * @dst: clipped destination coordinates of the plane
> - * @visible: visibility of the plane
>   * @state: backpointer to global drm_atomic_state
>   */
>  struct drm_plane_state {
>  	struct drm_plane *plane;
>  
> -	struct drm_crtc *crtc;   /* do not write directly, use drm_atomic_set_crtc_for_plane() */
> -	struct drm_framebuffer *fb;  /* do not write directly, use drm_atomic_set_fb_for_plane() */
> -	struct dma_fence *fence; /* do not write directly, use drm_atomic_set_fence_for_plane() */
> +	/**
> +	 * @crtc:
> +	 *
> +	 * currently bound CRTC, NULL if disabled
> +	 *
> +	 * do not write directly, use drm_atomic_set_crtc_for_plane()
> +	 */
> +	struct drm_crtc *crtc;
> +
> +	/**
> +	 * @fb:
> +	 *
> +	 * currently bound framebuffer
> +	 *
> +	 * do not write directly, use drm_atomic_set_fb_for_plane()
> +	 */
> +	struct drm_framebuffer *fb;
> +
> +	/**
> +	 * @fence:
> +	 *
> +	 * optional fence to wait for before scanning out @fb
> +	 *
> +	 * do not write directly, use drm_atomic_set_fence_for_plane()
> +	 */
> +	struct dma_fence *fence;
> +
> +	/**
> +	 * @crtc_x:
> +	 *
> +	 * left position of visible portion of plane on crtc
> +	 *
> +	 * Signed dest location allows it to be partially off screen.
> +	 */
> +
> +	int32_t crtc_x;
> +	/**
> +	 * @crtc_y:
> +	 *
> +	 * upper position of visible portion of plane on crtc
> +	 *
> +	 * Signed dest location allows it to be partially off screen.
> +	 */
> +	int32_t crtc_y;
>  
> -	/* Signed dest location allows it to be partially off screen */
> -	int32_t crtc_x, crtc_y;
>  	uint32_t crtc_w, crtc_h;
>  
>  	/* Source values are 16.16 fixed point */
> @@ -79,7 +112,11 @@ struct drm_plane_state {
>  	/* Clipped coordinates */
>  	struct drm_rect src, dst;
>  
> -	/*
> +	/**
> +	 * @visible:
> +	 *
> +	 * visibility of the plane
> +	 *
>  	 * Is the plane actually visible? Can be false even
>  	 * if fb!=NULL and crtc!=NULL, due to clipping.
>  	 */
> -- 
> 2.5.5
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch