[PATCH] hw/misc/auxbus: Improve aux_bus_init() docstring

[PATCH] hw/misc/auxbus: Improve aux_bus_init() docstring

[Philippe Mathieu-Daudé]

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.
-- 
2.31.1

Re: [PATCH] hw/misc/auxbus: Improve aux_bus_init() docstring

[Philippe Mathieu-Daudé]

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.
> 

Re: [PATCH] hw/misc/auxbus: Improve aux_bus_init() docstring

[Peter Maydell]

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