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

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Fri, 7 Aug 2020, Jan Beulich wrote:
> 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?

Yes, good catch, I'll change it.