doc: always use 'None' for functions not returning a value

It is preferred to state the absence of a return value explicitly in the doxygen-stile comments. Currently there are different styles of doing this, including: @return None @return NULL @return void @return N/A This patch unifies the above with `@return None`. Tracked-On: #1595 Signed-off-by: Junjie Mao <junjie.mao@intel.com>
2025-07-31 23:38:24 +00:00 · 2018-11-21 17:27:56 +08:00 · 2018-11-21 17:27:56 +08:00 · 97eb72a4a0
commit 97eb72a4a0
parent cbe1b74eee
13 changed files with 51 additions and 51 deletions
--- a/devicemodel/hw/pci/core.c
+++ b/devicemodel/hw/pci/core.c
@ -1644,7 +1644,7 @@ pci_msix_enabled(struct pci_vdev *dev)
 * @param dev Pointer to struct pci_vdev representing virtual PCI device.
 * @param index MSIx table entry index.
 *
- * @return N/A
+ * @return None
 */
 void
 pci_generate_msix(struct pci_vdev *dev, int index)
@ -1673,7 +1673,7 @@ pci_generate_msix(struct pci_vdev *dev, int index)
 * @param dev Pointer to struct pci_vdev representing virtual PCI device.
 * @param index Message data index.
 *
- * @return N/A
+ * @return None
 */
 void
 pci_generate_msi(struct pci_vdev *dev, int index)
@ -1781,7 +1781,7 @@ pci_lintr_route(struct pci_vdev *dev)
 *
 * @param dev Pointer to struct pci_vdev representing virtual PCI device.
 *
- * @return N/A
+ * @return None
 */
 void
 pci_lintr_assert(struct pci_vdev *dev)
@ -1804,7 +1804,7 @@ pci_lintr_assert(struct pci_vdev *dev)
 *
 * @param dev Pointer to struct pci_vdev representing virtual PCI device.
 *
- * @return N/A
+ * @return None
 */
 void
 pci_lintr_deassert(struct pci_vdev *dev)
--- a/devicemodel/hw/pci/virtio/virtio.c
+++ b/devicemodel/hw/pci/virtio/virtio.c
@ -55,7 +55,7 @@
 * @param dev Pointer to struct pci_vdev which emulates a PCI device.
 * @param queues Pointer to struct virtio_vq_info, normally an array.
 *
- * @return NULL
+ * @return None
 */
 void
 virtio_linkup(struct virtio_base *base, struct virtio_ops *vops,
@ -89,7 +89,7 @@ virtio_linkup(struct virtio_base *base, struct virtio_ops *vops,
 *
 * @param base Pointer to struct virtio_base.
 *
- * @return N/A
+ * @return None
 */
 void
 virtio_reset_dev(struct virtio_base *base)
@ -133,7 +133,7 @@ virtio_reset_dev(struct virtio_base *base)
 * @param base Pointer to struct virtio_base.
 * @param barnum Which BAR[0..5] to use.
 *
- * @return N/A
+ * @return None
 */
 void
 virtio_set_io_bar(struct virtio_base *base, int barnum)
@ -1078,7 +1078,7 @@ virtio_set_modern_bar(struct virtio_base *base, bool use_notify_pio)
 *
 * @param base Pointer to struct virtio_base.
 *
- * @return N/A
+ * @return None
 */
 void
 virtio_dev_error(struct virtio_base *base)
@ -1716,7 +1716,7 @@ virtio_pci_read(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
 * @param size Access range in bytes.
 * @param value Data value to be written into register.
 *
- * @return N/A
+ * @return None
 */
 void
 virtio_pci_write(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
--- a/devicemodel/include/pci_core.h
+++ b/devicemodel/include/pci_core.h
@ -259,7 +259,7 @@ int	pci_emul_add_pciecap(struct pci_vdev *pi, int pcie_device_type);
 * @param dev Pointer to struct pci_vdev representing virtual PCI device.
 * @param index Message data index.
 *
- * @return N/A
+ * @return None
 */
 void	pci_generate_msi(struct pci_vdev *dev, int index);

@ -269,7 +269,7 @@ void	pci_generate_msi(struct pci_vdev *dev, int index);
 * @param dev Pointer to struct pci_vdev representing virtual PCI device.
 * @param index MSIs table entry index.
 *
- * @return N/A
+ * @return None
 */
 void	pci_generate_msix(struct pci_vdev *dev, int index);

@ -278,7 +278,7 @@ void	pci_generate_msix(struct pci_vdev *dev, int index);
 *
 * @param dev Pointer to struct pci_vdev representing virtual PCI device.
 *
- * @return N/A
+ * @return None
 */
 void	pci_lintr_assert(struct pci_vdev *dev);

@ -287,7 +287,7 @@ void	pci_lintr_assert(struct pci_vdev *dev);
 *
 * @param dev Pointer to struct pci_vdev representing virtual PCI device.
 *
- * @return N/A
+ * @return None
 */
 void	pci_lintr_deassert(struct pci_vdev *dev);

@ -324,7 +324,7 @@ void	pciaccess_cleanup(void);
 * @param offset Offset in configuration space.
 * @param val Value in 1 byte.
 *
- * @return N/A
+ * @return None
 */
 static inline void
 pci_set_cfgdata8(struct pci_vdev *dev, int offset, uint8_t val)
@ -340,7 +340,7 @@ pci_set_cfgdata8(struct pci_vdev *dev, int offset, uint8_t val)
 * @param offset Offset in configuration space.
 * @param val Value in 2 bytes.
 *
- * @return N/A
+ * @return None
 */
 static inline void
 pci_set_cfgdata16(struct pci_vdev *dev, int offset, uint16_t val)
@ -356,7 +356,7 @@ pci_set_cfgdata16(struct pci_vdev *dev, int offset, uint16_t val)
 * @param offset Offset in configuration space.
 * @param val Value in 4 bytes.
 *
- * @return N/A
+ * @return None
 */
 static inline void
 pci_set_cfgdata32(struct pci_vdev *dev, int offset, uint32_t val)
--- a/devicemodel/include/virtio.h
+++ b/devicemodel/include/virtio.h
@ -648,7 +648,7 @@ vq_has_descs(struct virtio_vq_info *vq)
 * @param vb Pointer to struct virtio_base.
 * @param vq Pointer to struct virtio_vq_info.
 *
- * @return NULL
+ * @return None
 */
 static inline void
 vq_interrupt(struct virtio_base *vb, struct virtio_vq_info *vq)
@ -671,7 +671,7 @@ vq_interrupt(struct virtio_base *vb, struct virtio_vq_info *vq)
 *
 * @param vb Pointer to struct virtio_base.
 *
- * @return NULL.
+ * @return None
 */
 static inline void
 virtio_config_changed(struct virtio_base *vb)
@ -704,7 +704,7 @@ struct iovec;
 * @param dev Pointer to struct pci_vdev which emulates a PCI device.
 * @param queues Pointer to struct virtio_vq_info, normally an array.
 *
- * @return NULL
+ * @return None
 */
 void virtio_linkup(struct virtio_base *base, struct virtio_ops *vops,
 		   void *pci_virtio_dev, struct pci_vdev *dev,
@ -751,7 +751,7 @@ int virtio_intr_init(struct virtio_base *base, int barnum, int use_msix);
 *
 * @param base Pointer to struct virtio_base.
 *
- * @return N/A
+ * @return None
 */
 void virtio_reset_dev(struct virtio_base *base);

@ -761,7 +761,7 @@ void virtio_reset_dev(struct virtio_base *base);
 * @param base Pointer to struct virtio_base.
 * @param barnum Which BAR[0..5] to use.
 *
- * @return N/A
+ * @return None
 */
 void virtio_set_io_bar(struct virtio_base *base, int barnum);

@ -787,7 +787,7 @@ int vq_getchain(struct virtio_vq_info *vq, uint16_t *pidx,
 *
 * @param vq Pointer to struct virtio_vq_info.
 *
- * @return N/A
+ * @return None
 */
 void vq_retchain(struct virtio_vq_info *vq);

@ -799,7 +799,7 @@ void vq_retchain(struct virtio_vq_info *vq);
 * @param idx Pointer to available ring position, returned by vq_getchain().
 * @param iolen Number of data bytes to be returned to frontend.
 *
- * @return N/A
+ * @return None
 */
 void vq_relchain(struct virtio_vq_info *vq, uint16_t idx, uint32_t iolen);

@ -812,7 +812,7 @@ void vq_relchain(struct virtio_vq_info *vq, uint16_t idx, uint32_t iolen);
 * @param vq Pointer to struct virtio_vq_info.
 * @param used_all_avail Flag indicating if driver used all available chains.
 *
- * @return N/A
+ * @return None
 */
 void vq_endchains(struct virtio_vq_info *vq, int used_all_avail);

@ -848,7 +848,7 @@ uint64_t virtio_pci_read(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
 * @param size Access range in bytes.
 * @param value Data value to be written into register.
 *
- * @return N/A
+ * @return None
 */
 void virtio_pci_write(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
 		      int baridx, uint64_t offset, int size, uint64_t value);
@ -862,7 +862,7 @@ void virtio_pci_write(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
 *
 * @param base Pointer to struct virtio_base.
 *
- * @return N/A
+ * @return None
 */
 void virtio_dev_error(struct virtio_base *base);

--- a/hypervisor/arch/x86/guest/vlapic.c
+++ b/hypervisor/arch/x86/guest/vlapic.c
@ -540,7 +540,7 @@ vlapic_set_intr_ready(struct acrn_vlapic *vlapic, uint32_t vector, bool level)
 *
 * @param[in] dest_pcpu_id Target CPU ID.
 *
- * @return void
+ * @return None
 */
 void vlapic_post_intr(uint16_t dest_pcpu_id)
 {
@ -1361,7 +1361,7 @@ vlapic_pending_intr(const struct acrn_vlapic *vlapic, uint32_t *vecptr)
 * @param[in] vlapic Pointer to target vLAPIC data structure
 * @param[in] vector Target virtual interrupt vector
 *
- * @return void
+ * @return None
 *
 * @pre vlapic != NULL
 */
--- a/hypervisor/common/io_request.c
+++ b/hypervisor/common/io_request.c
@ -60,7 +60,7 @@ static void acrn_print_request(uint16_t vcpu_id, const struct vhm_request *req)
 *
 * @param vm The VM whose IO requests to be reset
 *
- * @return N/A
+ * @return None
 */
 void reset_vm_ioreqs(struct acrn_vm *vm)
 {
@ -96,7 +96,7 @@ static bool has_complete_ioreq(struct acrn_vcpu *vcpu)
 *
 * @param pcpu_id The physical cpu id of vcpu whose IO request to be checked
 *
- * @return N/A
+ * @return None
 */
 void handle_complete_ioreq(uint16_t pcpu_id)
 {
--- a/hypervisor/dm/vioapic.c
+++ b/hypervisor/dm/vioapic.c
@ -120,7 +120,7 @@ vioapic_set_pinstate(struct acrn_vioapic *vioapic, uint16_t pin, uint32_t level)
 *			GSI_RAISING_PULSE/GSI_FALLING_PULSE
 *
 * @pre irq < vioapic_pincount(vm)
- * @return void
+ * @return None
 */
 void
 vioapic_set_irq_nolock(struct acrn_vm *vm, uint32_t irq, uint32_t operation)
@ -163,7 +163,7 @@ vioapic_set_irq_nolock(struct acrn_vm *vm, uint32_t irq, uint32_t operation)
 *
 * @pre irq < vioapic_pincount(vm)
 *
- * @return void
+ * @return None
 */
 void
 vioapic_set_irq(struct acrn_vm *vm, uint32_t irq, uint32_t operation)
--- a/hypervisor/dm/vpic.c
+++ b/hypervisor/dm/vpic.c
@ -449,7 +449,7 @@ static void vpic_set_pinstate(struct acrn_vpic *vpic, uint8_t pin,
 * @param[in] operation action options:GSI_SET_HIGH/GSI_SET_LOW/
 *			GSI_RAISING_PULSE/GSI_FALLING_PULSE
 *
- * @return void
+ * @return None
 */
 void vpic_set_irq(struct acrn_vm *vm, uint32_t irq, uint32_t operation)
 {
@ -526,7 +526,7 @@ void vpic_get_irq_trigger(struct acrn_vm *vm, uint32_t irq,
 * @param[inout] vecptr Pointer to vector buffer and will be filled
 *			with eligible vector if any.
 *
- * @return void.
+ * @return None
 */
 void vpic_pending_intr(struct acrn_vm *vm, uint32_t *vecptr)
 {
@ -585,7 +585,7 @@ static void vpic_pin_accepted(struct i8259_reg_state *i8259, uint8_t pin)
 * @param[in] vm     Pointer to target VM
 * @param[in] vector Target virtual interrupt vector
 *
- * @return void
+ * @return None
 *
 * @pre vm != NULL
 */
--- a/hypervisor/include/arch/x86/guest/vioapic.h
+++ b/hypervisor/include/arch/x86/guest/vioapic.h
@ -80,7 +80,7 @@ void	vioapic_reset(struct acrn_vioapic *vioapic);
 *
 * @pre irq < vioapic_pincount(vm)
 *
- * @return void
+ * @return None
 */
 void	vioapic_set_irq(struct acrn_vm *vm, uint32_t irq, uint32_t operation);

@ -96,7 +96,7 @@ void	vioapic_set_irq(struct acrn_vm *vm, uint32_t irq, uint32_t operation);
 *			GSI_RAISING_PULSE/GSI_FALLING_PULSE
 *
 * @pre irq < vioapic_pincount(vm)
- * @return void
+ * @return None
 */
 void	vioapic_set_irq_nolock(struct acrn_vm *vm, uint32_t irq, uint32_t operation);
 void	vioapic_update_tmr(struct acrn_vcpu *vcpu);
--- a/hypervisor/include/arch/x86/guest/vlapic.h
+++ b/hypervisor/include/arch/x86/guest/vlapic.h
@ -145,7 +145,7 @@ int vlapic_pending_intr(const struct acrn_vlapic *vlapic, uint32_t *vecptr);
 * @param[in] vlapic Pointer to target vLAPIC data structure
 * @param[in] vector Target virtual interrupt vector
 *
- * @return void
+ * @return None
 *
 * @pre vlapic != NULL
 */
@ -161,7 +161,7 @@ void vlapic_intr_accepted(struct acrn_vlapic *vlapic, uint32_t vector);
 *
 * @param[in] dest_pcpu_id Target CPU ID.
 *
- * @return void
+ * @return None
 */
 void vlapic_post_intr(uint16_t dest_pcpu_id);

--- a/hypervisor/include/arch/x86/guest/vpic.h
+++ b/hypervisor/include/arch/x86/guest/vpic.h
@ -148,7 +148,7 @@ void vpic_init(struct acrn_vm *vm);
 * @param[in] operation action options:GSI_SET_HIGH/GSI_SET_LOW/
 *			GSI_RAISING_PULSE/GSI_FALLING_PULSE
 *
- * @return void
+ * @return None
 */
 void vpic_set_irq(struct acrn_vm *vm, uint32_t irq, uint32_t operation);

@ -159,7 +159,7 @@ void vpic_set_irq(struct acrn_vm *vm, uint32_t irq, uint32_t operation);
 * @param[inout] vecptr Pointer to vector buffer and will be filled
 *			with eligible vector if any.
 *
- * @return void.
+ * @return None
 */
 void vpic_pending_intr(struct acrn_vm *vm, uint32_t *vecptr);

@ -169,7 +169,7 @@ void vpic_pending_intr(struct acrn_vm *vm, uint32_t *vecptr);
 * @param[in] vm     Pointer to target VM
 * @param[in] vector Target virtual interrupt vector
 *
- * @return void
+ * @return None
 *
 * @pre vm != NULL
 */
--- a/hypervisor/include/arch/x86/ioreq.h
+++ b/hypervisor/include/arch/x86/ioreq.h
@ -292,7 +292,7 @@ int32_t acrn_insert_request_wait(struct acrn_vcpu *vcpu, const struct io_request
 *
 * @param vm The VM whose IO requests to be reset
 *
- * @return N/A
+ * @return None
 */
 void reset_vm_ioreqs(struct acrn_vm *vm);

@ -301,7 +301,7 @@ void reset_vm_ioreqs(struct acrn_vm *vm);
 *
 * @param pcpu_id The physical cpu id of vcpu whose IO request to be checked
 *
- * @return N/A
+ * @return None
 */
 void handle_complete_ioreq(uint16_t pcpu_id);

--- a/hypervisor/include/arch/x86/irq.h
+++ b/hypervisor/include/arch/x86/irq.h
@ -150,7 +150,7 @@ int vcpu_queue_exception(struct acrn_vcpu *vcpu, uint32_t vector, uint32_t err_c
 *
 * @param[in] vcpu Pointer to vCPU.
 *
- * @return void
+ * @return None
 *
 * @pre vcpu != NULL
 */
@ -161,7 +161,7 @@ void vcpu_inject_extint(struct acrn_vcpu *vcpu);
 *
 * @param[in] vcpu Pointer to vCPU.
 *
- * @return void
+ * @return None
 *
 * @pre vcpu != NULL
 */
@ -173,7 +173,7 @@ void vcpu_inject_nmi(struct acrn_vcpu *vcpu);
 * @param[in] vcpu     Pointer to vCPU.
 * @param[in] err_code Error Code to be injected.
 *
- * @return void
+ * @return None
 *
 * @pre vcpu != NULL
 */
@ -186,7 +186,7 @@ void vcpu_inject_gp(struct acrn_vcpu *vcpu, uint32_t err_code);
 * @param[in] addr     Address that result in PF.
 * @param[in] err_code Error Code to be injected.
 *
- * @return void
+ * @return None
 *
 * @pre vcpu != NULL
 */
@ -197,7 +197,7 @@ void vcpu_inject_pf(struct acrn_vcpu *vcpu, uint64_t addr, uint32_t err_code);
 *
 * @param[in] vcpu Pointer to vCPU.
 *
- * @return void
+ * @return None
 *
 * @pre vcpu != NULL
 */
@ -208,7 +208,7 @@ void vcpu_inject_ud(struct acrn_vcpu *vcpu);
 *
 * @param[in] vcpu Pointer to vCPU.
 *
- * @return void
+ * @return None
 *
 * @pre vcpu != NULL
 */
@ -219,7 +219,7 @@ void vcpu_inject_ac(struct acrn_vcpu *vcpu);
 *
 * @param[in] vcpu Pointer to vCPU.
 *
- * @return void
+ * @return None
 *
 * @pre vcpu != NULL
 */