kernel-doc ixes
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
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
@@ -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
PATCH 2/5 kernel-doc: Handle function typedefs without asterisks
In reply to Eduardo HabkostExample 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
@@ -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
PATCH 3/5 qom: Explicitly tag doc comments for typedefs and structs
In reply to Eduardo HabkostIf 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
@@ -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 ObjectPropertytypedef 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 TypeInfoOBJECT_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
PATCH 4/5 memory: Explicitly tag doc comments for structs
In reply to Eduardo HabkostThis 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
@@ -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
PATCH 5/5 kernel-doc: Remove $decl_type='type name' hack
In reply to Eduardo HabkostThe $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
@@ -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
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' hackinclude/exec/memory.h | 6 +++--- include/qom/object.h | 22 +++++++++++----------- scripts/kernel-doc | 16 +++------------- 3 files changed, 17 insertions(+), 27 deletions(-)