From: Helen Koike <helen.koike@collabora.com>
To: rmk+kernel@arm.linux.org.uk
Cc: gregkh@linuxfoundation.org, linux-kernel@vger.kernel.org
Subject: [PATCH 2/2] component: add kernel-docs in the header
Date: Mon, 17 Apr 2017 12:08:28 -0300
Message-Id: <1492441708-4057-2-git-send-email-helen.koike@collabora.com>
In-Reply-To: <1492441708-4057-1-git-send-email-helen.koike@collabora.com>
References: <1492441708-4057-1-git-send-email-helen.koike@collabora.com>
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 6893
Lines: 181

Add kernel-doc style documentation in component.h to facilitate
understanding the component system without reading the entire code.

Signed-off-by: Helen Koike <helen.koike@collabora.com>
---
 include/linux/component.h | 137 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 127 insertions(+), 10 deletions(-)

diff --git a/include/linux/component.h b/include/linux/component.h
index a15c094..eaea2b6 100644
--- a/include/linux/component.h
+++ b/include/linux/component.h
@@ -5,6 +5,14 @@
 
 struct device;
 
+/**
+ * struct component_ops - callbacks for the components
+ * @bind:	callback called when component_bind_all() is called
+ * @unbind:	callback called when component_unbind_all() is called
+ *
+ * Struct used to pass to the component system the callbacks to bind and unbind
+ * the component.
+ */
 struct component_ops {
 	int (*bind)(struct device *comp, struct device *master,
 		    void *master_data);
@@ -12,32 +20,141 @@ struct component_ops {
 		       void *master_data);
 };
 
-int component_add(struct device *, const struct component_ops *);
+/**
+ * component_add - add dev as a component in the component system
+ * @dev:	The component device
+ * @ops:	The struct component_ops
+ *
+ * Add a struct device as a component in the component system with the
+ * corresponding bind/unbind callbacks.
+ */
+int component_add(struct device *dev, const struct component_ops *ops);
+
+/**
+ * component_del - remove a component from the component system
+ * @dev:	The component device
+ * @ops:	The struct component_ops previously used in component_add()
+ *
+ * Remove a struct device from the component system.
+ */
 void component_del(struct device *, const struct component_ops *);
 
+/**
+ * component_bind_all - bind all components from a given master
+ * @master:		The master device
+ * @master_data:	void pointer used as a parameter in struct component_ops
+ *			bind() callback
+ *
+ * Trigger the call to bind() from struct component_ops for all components
+ * associated with the master.
+ * All components must have been found before calling the function. Usually it
+ * should be called inside bind() from struct component_master_ops
+ */
 int component_bind_all(struct device *master, void *master_data);
+
+/**
+ * component_unbind_all - unbind all components from a given master
+ * @master:		The master device
+ * @master_data:	void pointer used as a parameter in struct component_ops
+ *			unbind() callback
+ *
+ * Trigger the call to unbind() from struct component_ops for all components
+ * associated with the master.
+ */
 void component_unbind_all(struct device *master, void *master_data);
 
+/**
+ * struct component_master_ops - callbacks for the master
+ * @bind:	callback called when all the master's components are found
+ * @unbind:	callback called when taking down the master. The master can be
+ *		taken down if explicitly deleted or if one of its components is
+ *		deleted from the component system.
+ *
+ * Struct used to pass to the component system the callbacks to bind and unbind
+ * the master.
+ */
 struct component_master_ops {
 	int (*bind)(struct device *master);
 	void (*unbind)(struct device *master);
 };
 
-void component_master_del(struct device *,
-	const struct component_master_ops *);
+/**
+ * component_master_del - remove a master from the component system
+ * @dev:	The master device
+ * @ops:	The struct component_master_ops previously used in
+ *		component_master_add_with_match()
+ *
+ * Remove a struct device previously added as a master device from the component
+ * system.
+ */
+void component_master_del(struct device *dev,
+			  const struct component_master_ops *ops);
 
+/**
+ * struct component_match - match items holder
+ *
+ * This is an internal struct used to hold the match items created with
+ * component_match_add* before adding the master to the component system with
+ * component_master_add_with_match()
+ */
 struct component_match;
 
-int component_master_add_with_match(struct device *,
-	const struct component_master_ops *, struct component_match *);
+/**
+ * component_master_add_with_match - add dev as a master in the component system
+ * @dev:	The master device
+ * @ops:	The struct component_master_ops
+ * @match:	The struct component_match previously created with
+ *		component_macth_add*()
+ *
+ * Add a struct device in the component system as a master device with the
+ * corresponding bind/unbind callbacks and the list of match items.
+ * Each match item correspond to a component. When all the corresponding
+ * components are found, ops->bind() is called.
+ * If the master is bound and one of the components is removed, then
+ * ops->unbind() is called.
+ */
+int component_master_add_with_match(struct device *master,
+				    const struct component_master_ops *ops,
+				    struct component_match *match);
+
+/**
+ * component_match_add_release - associate a match item to the master
+ * @master:	The master device
+ * @matchptr:	The pointer to the match item array. If NULL then the array will
+ *		be allocated.
+ * @release:	Function called when the master releases the match item
+ * @compare:	Function called to check if a component correspond to the match
+ *		item
+ * @cb_data:	Void pointer used in release and compare callbacks
+ *
+ * Add a new match item associated with the master device.
+ * Each match item correspond to a component to be associated with this master.
+ * When the master is added in the component system by
+ * component_master_add_with_match(), the system will try to find the
+ * appropriate component by calling compare(). If compare succeeds, then the
+ * component is associated with the given match item.
+ */
 void component_match_add_release(struct device *master,
-	struct component_match **matchptr,
-	void (*release)(struct device *, void *),
-	int (*compare)(struct device *, void *), void *compare_data);
+			struct component_match **matchptr,
+			void (*release)(struct device *master, void *cb_data),
+			int (*compare)(struct device *comp, void *cb_data),
+			void *cb_data);
 
+/**
+ * component_match_add - associate a match item to the master
+ * @master:	The master device
+ * @matchptr:	The pointer to the match item array. If NULL then the array will
+ *		be allocated.
+ * @compare:	Function called to check if a component correspond to the match
+ *		item
+ * @compare_data: Void pointer used in release and compare callbacks
+ *
+ * Same as component_match_add_release() but with release argument as NULL
+ */
 static inline void component_match_add(struct device *master,
-	struct component_match **matchptr,
-	int (*compare)(struct device *, void *), void *compare_data)
+			struct component_match **matchptr,
+			int (*compare)(struct device *comp, void *compare_data),
+			void *compare_data)
 {
 	component_match_add_release(master, matchptr, NULL, compare,
 				    compare_data);
-- 
2.7.4