Re: [PATCH v3 2/2] drm: bridge: Add missing headerdocs for older bridge functions

[Daniel Vetter <daniel@ffwll.ch>]

On Tue, May 19, 2015 at 02:05:05PM +0530, Archit Taneja wrote:
> Add headerdocs for drm_bridge_add, drm_bridge_remove, drm_bridge_attach and
> of_drm_find_bridge.
> 
> Signed-off-by: Archit Taneja <architt@codeaurora.org>

You also need to pull in the kerneldoc into the drm.tmpl DocBook template
to include into the drm docs. You can generate those with

$ make htmldocs -k

-k because right now 802 docs are broken :( Also it'd be awesome if you
could include a short DOC: section to describe the design&goal of
drm_bridge quickly and also include that into the DocBook.

> ---
>  drivers/gpu/drm/drm_bridge.c | 28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)
> 
> diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c
> index f70e617..ceb8121 100644
> --- a/drivers/gpu/drm/drm_bridge.c
> +++ b/drivers/gpu/drm/drm_bridge.c
> @@ -31,6 +31,11 @@
>  static DEFINE_MUTEX(bridge_lock);
>  static LIST_HEAD(bridge_list);
>  
> +/**
> + * drm_bridge_add - add the given bridge to the global bridge list
> + *
> + * @bridge: bridge control structure

For functions which return something it's good to add a Returns: section
describing the semantics of the return codes. Copypasting something
suitable from other kerneldoc is good for consistency ;-)

Cheers, Daniel

> + */
>  int drm_bridge_add(struct drm_bridge *bridge)
>  {
>  	mutex_lock(&bridge_lock);
> @@ -41,6 +46,11 @@ int drm_bridge_add(struct drm_bridge *bridge)
>  }
>  EXPORT_SYMBOL(drm_bridge_add);
>  
> +/**
> + * drm_bridge_remove - remove the given bridge from the global bridge list
> + *
> + * @bridge: bridge control structure
> + */
>  void drm_bridge_remove(struct drm_bridge *bridge)
>  {
>  	mutex_lock(&bridge_lock);
> @@ -49,6 +59,18 @@ void drm_bridge_remove(struct drm_bridge *bridge)
>  }
>  EXPORT_SYMBOL(drm_bridge_remove);
>  
> +/**
> + * drm_bridge_attach - associate given bridge to our DRM device
> + *
> + * @dev: DRM device
> + * @bridge: bridge control structure
> + *
> + * called by a kms driver to link one of our encoder/bridge to the given
> + * bridge.
> + *
> + * Note that setting up links between the bridge and our encoder/bridge
> + * objects needs to be handled by the kms driver itself
> + */
>  int drm_bridge_attach(struct drm_device *dev, struct drm_bridge *bridge)
>  {
>  	if (!dev || !bridge)
> @@ -211,6 +233,12 @@ void drm_bridge_enable(struct drm_bridge *bridge)
>  EXPORT_SYMBOL(drm_bridge_enable);
>  
>  #ifdef CONFIG_OF
> +/**
> + * of_drm_find_bridge - find the bridge corresponding to the device node in
> + *			the global bridge list
> + *
> + * @np: device node
> + */
>  struct drm_bridge *of_drm_find_bridge(struct device_node *np)
>  {
>  	struct drm_bridge *bridge;
> -- 
> The Qualcomm Innovation Center, Inc. is a member of the Code Aurora Forum,
> hosted by The Linux Foundation
> 

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