Re: [PATCH 04/14] kernel-doc: public/event_channel.h

[Jan Beulich <jbeulich@xxxxxxxx>]

On 07.08.2020 01:49, Stefano Stabellini wrote:
> @@ -137,65 +147,78 @@ typedef struct evtchn_bind_interdomain 
> evtchn_bind_interdomain_t;
>   *     binding cannot be changed.
>   */
>  struct evtchn_bind_virq {
> -    /* IN parameters. */
> -    uint32_t virq; /* enum virq */
> +    /** @virq: IN parameter, enum virq */
> +    uint32_t virq;
> +    /** @vcpu: IN parameter */
>      uint32_t vcpu;
> -    /* OUT parameters. */
> +    /** @port: OUT parameter */
>      evtchn_port_t port;
>  };
>  typedef struct evtchn_bind_virq evtchn_bind_virq_t;
>  
> -/*
> - * EVTCHNOP_bind_pirq: Bind a local event channel to a real IRQ (PIRQ <irq>).
> +/**
> + * struct evtchn_bind_pirq - EVTCHNOP_bind_pirq
> + *
> + * Bind a local event channel to a real IRQ (PIRQ <irq>).
>   * NOTES:
>   *  1. A physical IRQ may be bound to at most one event channel per domain.
>   *  2. Only a sufficiently-privileged domain may bind to a physical IRQ.
>   */
>  struct evtchn_bind_pirq {
> -    /* IN parameters. */
> +    /** @pirq: IN parameter */
>      uint32_t pirq;
> +    /** @flags: IN parameter,  BIND_PIRQ__* */
>  #define BIND_PIRQ__WILL_SHARE 1
> -    uint32_t flags; /* BIND_PIRQ__* */
> -    /* OUT parameters. */
> +    uint32_t flags;
> +    /** @port: OUT parameter */
>      evtchn_port_t port;
>  };
>  typedef struct evtchn_bind_pirq evtchn_bind_pirq_t;
>  
> -/*
> - * EVTCHNOP_bind_ipi: Bind a local event channel to receive events.
> +/**
> + * struct struct evtchn_bind_ipi - EVTCHNOP_bind_ipi
> + *
> + * Bind a local event channel to receive events.
>   * NOTES:
>   *  1. The allocated event channel is bound to the specified vcpu. The 
> binding
>   *     may not be changed.
>   */
>  struct evtchn_bind_ipi {
> +    /** @vcpu: IN parameter */
>      uint32_t vcpu;
> -    /* OUT parameters. */
> +    /** @port: OUT parameter */
>      evtchn_port_t port;
>  };
>  typedef struct evtchn_bind_ipi evtchn_bind_ipi_t;
>  
> -/*
> - * EVTCHNOP_close: Close a local event channel <port>. If the channel is
> - * interdomain then the remote end is placed in the unbound state
> +/**
> + * struct evtchn_close - EVTCHNOP_close
> + *
> + * Close a local event channel <port>. If the channel is interdomain
> + * then the remote end is placed in the unbound state
>   * (EVTCHNSTAT_unbound), awaiting a new connection.
>   */
>  struct evtchn_close {
> -    /* IN parameters. */
> +    /** @port: IN parameter */
>      evtchn_port_t port;
>  };
>  typedef struct evtchn_close evtchn_close_t;
>  
> -/*
> - * EVTCHNOP_send: Send an event to the remote end of the channel whose local
> - * endpoint is <port>.
> +/**
> + * struct evtchn_send - EVTCHNOP_send
> + *
> + * Send an event to the remote end of the channel whose local endpoint
> + * is <port>.
>   */
>  struct evtchn_send {
> -    /* IN parameters. */
> +    /** @port: IN parameter */
>      evtchn_port_t port;
>  };
>  typedef struct evtchn_send evtchn_send_t;
>  
> -/*
> +/**
> + * struct evtchn_status - EVTCHNOP_status
> + *
>   * EVTCHNOP_status: Get the current status of the communication channel which
>   * has an endpoint at <dom, port>.
>   * NOTES:

Nit: I guess you meant to remove the "EVTCHNOP_status: " prefix from
the original comment, like is done elsewhere?

Jan