[PATCH 4/4] drm: Add a few missing descriptions in drm_driver docs

[Daniel Vetter]

On Thu, Jul 20, 2017 at 01:47:43PM -0400, Sean Paul wrote:
> Fixes the following warnings when building docs:
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'debugfs_init'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_open_object'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_close_object'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'prime_handle_to_fd'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'prime_fd_to_handle'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_prime_export'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_prime_import'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'gem_vm_ops'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'major'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'minor'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'patchlevel'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'name'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'desc'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'date'
> ../include/drm/drm_drv.h:553: warning: No description found for parameter 'driver_features'
> 
> There are still a couple more warnings for prime helpers that are documented elsewhere.
> 
> Signed-off-by: Sean Paul <seanpaul at chromium.org>

Yeah reviewing gem/prime docs is still on my todo, which is why these
aren't complete yet. Yours are a bit terse and we probably want an
overhaul of all the gem/prime docs, but at least a start.

Reviewed-by: Daniel Vetter <daniel.vetter at ffwll.ch>


> ---
>  include/drm/drm_drv.h | 52 +++++++++++++++++++++++++++++++++++++++++++++------
>  1 file changed, 46 insertions(+), 6 deletions(-)
> 
> diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h
> index 81971dc0b573..505c91354802 100644
> --- a/include/drm/drm_drv.h
> +++ b/include/drm/drm_drv.h
> @@ -390,6 +390,11 @@ struct drm_driver {
>  	 */
>  	void (*master_drop)(struct drm_device *dev, struct drm_file *file_priv);
>  
> +	/**
> +	 * @debugfs_init:
> +	 *
> +	 * Allows drivers to create driver-specific debugfs files.
> +	 */
>  	int (*debugfs_init)(struct drm_minor *minor);
>  
>  	/**
> @@ -408,7 +413,18 @@ struct drm_driver {
>  	 */
>  	void (*gem_free_object_unlocked) (struct drm_gem_object *obj);
>  
> +	/**
> +	 * @gem_open_object:
> +	 *
> +	 * Driver hook called upon gem handle creation
> +	 */
>  	int (*gem_open_object) (struct drm_gem_object *, struct drm_file *);
> +
> +	/**
> +	 * @gem_close_object:
> +	 *
> +	 * Driver hook called upon gem handle release
> +	 */
>  	void (*gem_close_object) (struct drm_gem_object *, struct drm_file *);
>  
>  	/**
> @@ -421,19 +437,34 @@ struct drm_driver {
>  						    size_t size);
>  
>  	/* prime: */
> -	/* export handle -> fd (see drm_gem_prime_handle_to_fd() helper) */
> +	/**
> +	 * @prime_handle_to_fd:
> +	 *
> +	 * export handle -> fd (see drm_gem_prime_handle_to_fd() helper)
> +	 */
>  	int (*prime_handle_to_fd)(struct drm_device *dev, struct drm_file *file_priv,
>  				uint32_t handle, uint32_t flags, int *prime_fd);
> -	/* import fd -> handle (see drm_gem_prime_fd_to_handle() helper) */
> +	/**
> +	 * @prime_fd_to_handle:
> +	 *
> +	 * import fd -> handle (see drm_gem_prime_fd_to_handle() helper)
> +	 */
>  	int (*prime_fd_to_handle)(struct drm_device *dev, struct drm_file *file_priv,
>  				int prime_fd, uint32_t *handle);
> -	/* export GEM -> dmabuf */
> +	/**
> +	 * @gem_prime_export:
> +	 *
> +	 * export GEM -> dmabuf
> +	 */
>  	struct dma_buf * (*gem_prime_export)(struct drm_device *dev,
>  				struct drm_gem_object *obj, int flags);
> -	/* import dmabuf -> GEM */
> +	/**
> +	 * @gem_prime_import:
> +	 *
> +	 * import dmabuf -> GEM
> +	 */
>  	struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,
>  				struct dma_buf *dma_buf);
> -	/* low-level interface used by drm_gem_prime_{import,export} */
>  	int (*gem_prime_pin)(struct drm_gem_object *obj);
>  	void (*gem_prime_unpin)(struct drm_gem_object *obj);
>  	struct reservation_object * (*gem_prime_res_obj)(
> @@ -505,16 +536,25 @@ struct drm_driver {
>  			    struct drm_device *dev,
>  			    uint32_t handle);
>  
> -	/* Driver private ops for this object */
> +	/**
> +	 * @gem_vm_ops: Driver private ops for this object
> +	 */
>  	const struct vm_operations_struct *gem_vm_ops;
>  
> +	/** @major: driver major number */
>  	int major;
> +	/** @minor: driver minor number */
>  	int minor;
> +	/** @patchlevel: driver patch level */
>  	int patchlevel;
> +	/** @name: driver name */
>  	char *name;
> +	/** @desc: driver description */
>  	char *desc;
> +	/** @date: driver date */
>  	char *date;
>  
> +	/** @driver_features: driver features */
>  	u32 driver_features;
>  
>  	/**
> -- 
> 2.14.0.rc0.284.gd933b75aa4-goog
> 
> _______________________________________________
> 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