| Message ID | 20211122104831.1052063-1-f4bug@amsat.org |
|---|---|
| State | New |
| Headers | show |
| Series | hw/misc/auxbus: Improve aux_bus_init() docstring | expand |
Cc'ing Peter for documentation review. On 11/22/21 11:48, Philippe Mathieu-Daudé wrote: > Mention in aux_bus_init() docstring that the AUXBus > is not simply initialized, it is also allocated. > > Signed-off-by: Philippe Mathieu-Daudé <f4bug@amsat.org> > --- > include/hw/misc/auxbus.h | 12 +++++++----- > 1 file changed, 7 insertions(+), 5 deletions(-) > > diff --git a/include/hw/misc/auxbus.h b/include/hw/misc/auxbus.h > index b05799d2f7a..bd8612018a7 100644 > --- a/include/hw/misc/auxbus.h > +++ b/include/hw/misc/auxbus.h > @@ -85,7 +85,8 @@ struct AUXSlave { > }; > > /** > - * aux_bus_init: Initialize an AUX bus. > + * aux_bus_init: > + * Create an AUX bus on the heap. > * > * Returns the new AUX bus created. > * > @@ -101,7 +102,7 @@ AUXBus *aux_bus_init(DeviceState *parent, const char *name); > */ > void aux_bus_realize(AUXBus *bus); > > -/* > +/** > * aux_request: Make a request on the bus. > * > * Returns the reply of the request. > @@ -115,7 +116,7 @@ void aux_bus_realize(AUXBus *bus); > AUXReply aux_request(AUXBus *bus, AUXCommand cmd, uint32_t address, > uint8_t len, uint8_t *data); > > -/* > +/** > * aux_get_i2c_bus: Get the i2c bus for I2C over AUX command. > * > * Returns the i2c bus associated to this AUX bus. > @@ -124,7 +125,7 @@ AUXReply aux_request(AUXBus *bus, AUXCommand cmd, uint32_t address, > */ > I2CBus *aux_get_i2c_bus(AUXBus *bus); > > -/* > +/** > * aux_init_mmio: Init an mmio for an AUX slave. > * > * @aux_slave The AUX slave. > @@ -132,7 +133,8 @@ I2CBus *aux_get_i2c_bus(AUXBus *bus); > */ > void aux_init_mmio(AUXSlave *aux_slave, MemoryRegion *mmio); > > -/* aux_map_slave: Map the mmio for an AUX slave on the bus. > +/** > + * aux_map_slave: Map the mmio for an AUX slave on the bus. > * > * @dev The AUX slave. > * @addr The address for the slave's mmio. >
On Mon, 22 Nov 2021 at 11:11, Philippe Mathieu-Daudé <f4bug@amsat.org> wrote: > > Mention in aux_bus_init() docstring that the AUXBus > is not simply initialized, it is also allocated. > > Signed-off-by: Philippe Mathieu-Daudé <f4bug@amsat.org> > --- > include/hw/misc/auxbus.h | 12 +++++++----- > 1 file changed, 7 insertions(+), 5 deletions(-) > > diff --git a/include/hw/misc/auxbus.h b/include/hw/misc/auxbus.h > index b05799d2f7a..bd8612018a7 100644 > --- a/include/hw/misc/auxbus.h > +++ b/include/hw/misc/auxbus.h > @@ -85,7 +85,8 @@ struct AUXSlave { > }; > > /** > - * aux_bus_init: Initialize an AUX bus. > + * aux_bus_init: > + * Create an AUX bus on the heap. > * > * Returns the new AUX bus created. > * > @@ -101,7 +102,7 @@ AUXBus *aux_bus_init(DeviceState *parent, const char *name); > */ > void aux_bus_realize(AUXBus *bus); > > -/* > +/** > * aux_request: Make a request on the bus. > * > * Returns the reply of the request. > @@ -115,7 +116,7 @@ void aux_bus_realize(AUXBus *bus); > AUXReply aux_request(AUXBus *bus, AUXCommand cmd, uint32_t address, > uint8_t len, uint8_t *data); > > -/* > +/** > * aux_get_i2c_bus: Get the i2c bus for I2C over AUX command. > * > * Returns the i2c bus associated to this AUX bus. > @@ -124,7 +125,7 @@ AUXReply aux_request(AUXBus *bus, AUXCommand cmd, uint32_t address, > */ > I2CBus *aux_get_i2c_bus(AUXBus *bus); > > -/* > +/** > * aux_init_mmio: Init an mmio for an AUX slave. > * > * @aux_slave The AUX slave. > @@ -132,7 +133,8 @@ I2CBus *aux_get_i2c_bus(AUXBus *bus); > */ > void aux_init_mmio(AUXSlave *aux_slave, MemoryRegion *mmio); > > -/* aux_map_slave: Map the mmio for an AUX slave on the bus. > +/** > + * aux_map_slave: Map the mmio for an AUX slave on the bus. > * > * @dev The AUX slave. > * @addr The address for the slave's mmio. If you want to turn these into /**-introduced kerneldoc-comment comments, then they need to be rearranged to have all the elements in the required order: /** * function_name - brief description * @arg1: Description of argument * @arg2: Description of argument * * Longer description paragraph if required. * * Return: Describe return value */ https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation This might be better done as a separate commit from fixing the comment text for aux_bus_init(). -- PMM
diff --git a/include/hw/misc/auxbus.h b/include/hw/misc/auxbus.h index b05799d2f7a..bd8612018a7 100644 --- a/include/hw/misc/auxbus.h +++ b/include/hw/misc/auxbus.h @@ -85,7 +85,8 @@ struct AUXSlave { }; /** - * aux_bus_init: Initialize an AUX bus. + * aux_bus_init: + * Create an AUX bus on the heap. * * Returns the new AUX bus created. * @@ -101,7 +102,7 @@ AUXBus *aux_bus_init(DeviceState *parent, const char *name); */ void aux_bus_realize(AUXBus *bus); -/* +/** * aux_request: Make a request on the bus. * * Returns the reply of the request. @@ -115,7 +116,7 @@ void aux_bus_realize(AUXBus *bus); AUXReply aux_request(AUXBus *bus, AUXCommand cmd, uint32_t address, uint8_t len, uint8_t *data); -/* +/** * aux_get_i2c_bus: Get the i2c bus for I2C over AUX command. * * Returns the i2c bus associated to this AUX bus. @@ -124,7 +125,7 @@ AUXReply aux_request(AUXBus *bus, AUXCommand cmd, uint32_t address, */ I2CBus *aux_get_i2c_bus(AUXBus *bus); -/* +/** * aux_init_mmio: Init an mmio for an AUX slave. * * @aux_slave The AUX slave. @@ -132,7 +133,8 @@ I2CBus *aux_get_i2c_bus(AUXBus *bus); */ void aux_init_mmio(AUXSlave *aux_slave, MemoryRegion *mmio); -/* aux_map_slave: Map the mmio for an AUX slave on the bus. +/** + * aux_map_slave: Map the mmio for an AUX slave on the bus. * * @dev The AUX slave. * @addr The address for the slave's mmio.
Mention in aux_bus_init() docstring that the AUXBus is not simply initialized, it is also allocated. Signed-off-by: Philippe Mathieu-Daudé <f4bug@amsat.org> --- include/hw/misc/auxbus.h | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-)