Skip to contentSkip to conversation

kernel-doc ixes

PATCH In review Eduardo Habkost 2 participants 7 messages Oct 3, 2020

lore
Share & tools
lore
#0 lore raw

cover kernel-doc ixes

Among other fixes in kernel-doc, this series get rid of QEMU-specific $decl_type='type name' hack in kernel-doc, because it made it impossible to document macros with names starting with uppercase letters (like most of the macros at qom/object.h).

Eduardo Habkost (5):
kernel-doc: Handle function typedefs that return pointers
kernel-doc: Handle function typedefs without asterisks
qom: Explicitly tag doc comments for typedefs and structs
memory: Explicitly tag doc comments for structs
kernel-doc: Remove $decl_type='type name' hack

 include/exec/memory.h |  6 +++---
 include/qom/object.h  | 22 +++++++++++-----------
 scripts/kernel-doc    | 16 +++-------------
 3 files changed, 17 insertions(+), 27 deletions(-)
Signature · 1 line
2.26.2
#1 lore raw

PATCH 1/5 kernel-doc: Handle function typedefs that return pointers

One example that was not being parsed correctly by kernel-doc is:

typedef Object *(ObjectPropertyResolve)(Object *obj,

                                          void *opaque,
                                          const char *part);
---
 scripts/kernel-doc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
scripts/kernel-doc +2 -2
index 40ad782e342..57a4a72970f 100755
@@ -1318,8 +1318,8 @@ sub dump_typedef($$) {
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
 
     # Parse function prototypes
-    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
-	$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
+    if ($x =~ /typedef\s+(\w+\s*\**)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
+	$x =~ /typedef\s+(\w+\s*\**)\s*(\w\S+)\s*\s*\((.*)\);/) {
 
 	# Function typedefs
 	$return_type = $1;
Signature · 1 line
2.26.2
#2 lore raw

PATCH 2/5 kernel-doc: Handle function typedefs without asterisks

In reply to Eduardo Habkost

Example of typedef that was not parsed by kernel-doc:

  typedef void (ObjectUnparent)(Object *obj);
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
scripts/kernel-doc +1 -1
index 57a4a72970f..57b911ff174 100755
@@ -1318,7 +1318,7 @@ sub dump_typedef($$) {
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
 
     # Parse function prototypes
-    if ($x =~ /typedef\s+(\w+\s*\**)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
+    if ($x =~ /typedef\s+(\w+\s*\**)\s*\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
 	$x =~ /typedef\s+(\w+\s*\**)\s*(\w\S+)\s*\s*\((.*)\);/) {
 
 	# Function typedefs
Signature · 1 line
2.26.2
#3 lore raw

PATCH 3/5 qom: Explicitly tag doc comments for typedefs and structs

In reply to Eduardo Habkost

If we explicitly indicate we are documenting a typedef or a struct, we'll be able to remove the $decl_type='type name' hack from kernel-doc.

---
 include/qom/object.h | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)
include/qom/object.h +11 -11
index 27aaa67e63f..32bdf4cce53 100644
@@ -31,7 +31,7 @@ typedef struct InterfaceInfo InterfaceInfo;
 typedef struct ObjectProperty ObjectProperty;
 
 /**
- * ObjectPropertyAccessor:
+ * typedef ObjectPropertyAccessor:
  * @obj: the object that owns the property
  * @v: the visitor that contains the property data
  * @name: the name of the property
@@ -47,7 +47,7 @@ typedef void (ObjectPropertyAccessor)(Object *obj,
                                       Error **errp);
 
 /**
- * ObjectPropertyResolve:
+ * typedef ObjectPropertyResolve:
  * @obj: the object that owns the property
  * @opaque: the opaque registered with the property
  * @part: the name of the property
@@ -66,7 +66,7 @@ typedef Object *(ObjectPropertyResolve)(Object *obj,
                                         const char *part);
 
 /**
- * ObjectPropertyRelease:
+ * typedef ObjectPropertyRelease:
  * @obj: the object that owns the property
  * @name: the name of the property
  * @opaque: the opaque registered with the property
@@ -78,7 +78,7 @@ typedef void (ObjectPropertyRelease)(Object *obj,
                                      void *opaque);
 
 /**
- * ObjectPropertyInit:
+ * typedef ObjectPropertyInit:
  * @obj: the object that owns the property
  * @prop: the property to set
  *
@@ -101,7 +101,7 @@ struct ObjectProperty
 };
 
 /**
- * ObjectUnparent:
+ * typedef ObjectUnparent:
  * @obj: the object that is being removed from the composition tree
  *
  * Called when an object is being removed from the QOM composition tree.
@@ -110,7 +110,7 @@ struct ObjectProperty
 typedef void (ObjectUnparent)(Object *obj);
 
 /**
- * ObjectFree:
+ * typedef ObjectFree:
  * @obj: the object being freed
  *
  * Called when an object's last reference is removed.
@@ -120,7 +120,7 @@ typedef void (ObjectFree)(void *obj);
 #define OBJECT_CLASS_CAST_CACHE 4
 
 /**
- * ObjectClass:
+ * struct ObjectClass:
  *
  * The base for all classes.  The only thing that #ObjectClass contains is an
  * integer type handle.
@@ -140,7 +140,7 @@ struct ObjectClass
 };
 
 /**
- * Object:
+ * struct Object:
  *
  * The base for all objects.  The first member of this object is a pointer to
  * a #ObjectClass.  Since C guarantees that the first member of a structure
@@ -370,7 +370,7 @@ struct Object
                                 true, { NULL })
 
 /**
- * TypeInfo:
+ * struct TypeInfo:
  * @name: The name of the type.
  * @parent: The name of the parent type.
  * @instance_size: The size of the object (derivative of #Object).  If
@@ -496,7 +496,7 @@ struct TypeInfo
     OBJECT_CLASS_CHECK(class, object_get_class(OBJECT(obj)), name)
 
 /**
- * InterfaceInfo:
+ * struct InterfaceInfo:
  * @type: The name of the interface.
  *
  * The information associated with an interface.
@@ -506,7 +506,7 @@ struct InterfaceInfo {
 };
 
 /**
- * InterfaceClass:
+ * struct InterfaceClass:
  * @parent_class: the base class
  *
  * The class for all interfaces.  Subclasses of this class should only add
Signature · 1 line
2.26.2
#4 lore raw

PATCH 4/5 memory: Explicitly tag doc comments for structs

In reply to Eduardo Habkost

This will allow us to remove the QEMU-specific $decl_type='type name' hack from the kernel-doc script.

---
 include/exec/memory.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
include/exec/memory.h +3 -3
index dee09851622..622207bde12 100644
@@ -443,7 +443,7 @@ struct IOMMUMemoryRegion {
     QLIST_FOREACH((n), &(mr)->iommu_notify, node)
 
 /**
- * MemoryListener: callbacks structure for updates to the physical memory map
+ * struct MemoryListener: callbacks structure for updates to the physical memory map
  *
  * Allows a component to adjust to changes in the guest-visible memory map.
  * Use with memory_listener_register() and memory_listener_unregister().
@@ -681,7 +681,7 @@ struct MemoryListener {
 };
 
 /**
- * AddressSpace: describes a mapping of addresses to #MemoryRegion objects
+ * struct AddressSpace: describes a mapping of addresses to #MemoryRegion objects
  */
 struct AddressSpace {
     /* private: */
@@ -721,7 +721,7 @@ static inline FlatView *address_space_to_flatview(AddressSpace *as)
 
 
 /**
- * MemoryRegionSection: describes a fragment of a #MemoryRegion
+ * struct MemoryRegionSection: describes a fragment of a #MemoryRegion
  *
  * @mr: the region, or %NULL if empty
  * @fv: the flat view of the address space the region is mapped in
Signature · 1 line
2.26.2
#5 lore raw

PATCH 5/5 kernel-doc: Remove $decl_type='type name' hack

In reply to Eduardo Habkost

The $decl_type='type name' hack makes it impossible to document macros with uppercase names (e.g. most of the macros in object.h).

Now that we have explicitly tagged the struct and typedef doc comments in memory.h and object.h, we don't need that hack anymore. This will make the documentation for the macros in object.h finally be rendered as expected.

---
 scripts/kernel-doc | 12 +-----------
 1 file changed, 1 insertion(+), 11 deletions(-)
scripts/kernel-doc +1 -11
index 57b911ff174..0ff62bb6a2d 100755
@@ -1064,14 +1064,6 @@ sub output_blockhead {
 sub dump_declaration($$) {
     no strict 'refs';
     my ($prototype, $file) = @_;
-    if ($decl_type eq 'type name') {
-       if ($prototype =~ /^(enum|struct|union)\s+/) {
-	   $decl_type = $1;
-	} else {
-	   return;
-       }
-    }
-
     my $func = "dump_" . $decl_type;
     &$func(@_);
 }
@@ -1928,9 +1920,7 @@ sub process_name($$) {
 	    ++$warnings;
 	}
 
-	if ($identifier =~ m/^[A-Z]/) {
-	    $decl_type = 'type name';
-	} elsif ($identifier =~ m/^struct\b/) {
+	if ($identifier =~ m/^struct\b/) {
 	    $decl_type = 'struct';
 	} elsif ($identifier =~ m/^union\b/) {
 	    $decl_type = 'union';
Signature · 1 line
2.26.2
Reviewed-by on the v1 series
#6 lore raw
In reply to Eduardo Habkost
Quoted 4 lines · Eduardo Habkost

Among other fixes in kernel-doc, this series get rid of QEMU-specific $decl_type='type name' hack in kernel-doc, because it made it impossible to document macros with names starting with uppercase letters (like most of the macros at qom/object.h).

Thanks, it seemed like a good idea but... it wasn't. :)

Paolo

Quoted 12 lines

Eduardo Habkost (5):
kernel-doc: Handle function typedefs that return pointers
kernel-doc: Handle function typedefs without asterisks
qom: Explicitly tag doc comments for typedefs and structs
memory: Explicitly tag doc comments for structs
kernel-doc: Remove $decl_type='type name' hack

 include/exec/memory.h |  6 +++---
 include/qom/object.h  | 22 +++++++++++-----------
 scripts/kernel-doc    | 16 +++-------------
 3 files changed, 17 insertions(+), 27 deletions(-)