Re: [PATCH] Fix kobject documentation

[Randy Dunlap <randy.dunlap@oracle.com>]

On Fri, 27 Jul 2007 13:21:15 +0200 Cornelia Huck wrote:

> On Fri, 27 Jul 2007 19:27:26 +0900,
> Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com> wrote:
> 
> > Fix kobject documentation as follows.
> > 
> >  - remove trailing spaces.
> >  - struct device_subsys -> devices_subsys
> > 
> > Signed-off-by: Satoru Takeuchi<takeuchi_satoru@jp.fujitsu.com>
> 
> This is certainly a start, but kobject.txt needs more updates. For
> example, it still refers to the removed struct subsystem, and
> uevent_ops are not mentioned. Looking at kobject.h, the kerneldoc there
> needs some updates as well...

Here's a start at that.
---


From: Randy Dunlap <randy.dunlap@oracle.com>

Removed kernel-doc marker (/**) from struct kset -- each struct member
still needs annotation.

Corrected one parameter name so that kernel-doc matches the macro.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
---
 include/linux/kobject.h |   23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

--- linux-2623-rc1g2.orig/include/linux/kobject.h
+++ linux-2623-rc1g2/include/linux/kobject.h
@@ -108,9 +108,15 @@ struct kobj_type {
 	struct attribute	** default_attrs;
 };
 
+struct kset_uevent_ops {
+	int (*filter)(struct kset *kset, struct kobject *kobj);
+	const char *(*name)(struct kset *kset, struct kobject *kobj);
+	int (*uevent)(struct kset *kset, struct kobject *kobj, char **envp,
+			int num_envp, char *buffer, int buffer_size);
+};
 
-/**
- *	kset - a set of kobjects of a specific type, belonging
+/*
+ *	struct kset - a set of kobjects of a specific type, belonging
  *	to a specific subsystem.
  *
  *	All kobjects of a kset should be embedded in an identical 
@@ -126,13 +132,6 @@ struct kobj_type {
  *	supress the event generation or add subsystem specific
  *	variables carried with the event.
  */
-struct kset_uevent_ops {
-	int (*filter)(struct kset *kset, struct kobject *kobj);
-	const char *(*name)(struct kset *kset, struct kobject *kobj);
-	int (*uevent)(struct kset *kset, struct kobject *kobj, char **envp,
-			int num_envp, char *buffer, int buffer_size);
-};
-
 struct kset {
 	struct kobj_type	* ktype;
 	struct list_head	list;
@@ -173,7 +172,7 @@ static inline struct kobj_type * get_kty
 extern struct kobject * kset_find_obj(struct kset *, const char *);
 
 
-/**
+/*
  * Use this when initializing an embedded kset with no other 
  * fields to initialize.
  */
@@ -198,7 +197,7 @@ extern struct kset kernel_subsys;
 /* The global /sys/hypervisor/ subsystem  */
 extern struct kset hypervisor_subsys;
 
-/**
+/*
  * Helpers for setting the kset of registered objects.
  * Often, a registered object belongs to a kset embedded in a 
  * subsystem. These do no magic, just make the resulting code
@@ -233,7 +232,7 @@ extern struct kset hypervisor_subsys;
 /**
  *	subsys_set_kset(obj,subsys) - set kset for subsystem
  *	@obj:		ptr to some object type.
- *	@subsys:	a subsystem object (not a ptr).
+ *	@_subsys:	a subsystem object (not a ptr).
  *
  *	Can be used for any object type with an embedded ->subsys.
  *	Sets the kset of @obj's kobject to @subsys.kset. This makes