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

From: Stefano Stabellini <sstabellini@kernel.org>
To: Jan Beulich <jbeulich@suse.com>
Cc: Stefano Stabellini <sstabellini@kernel.org>,
	julien@xen.org, wl@xen.org, andrew.cooper3@citrix.com,
	ian.jackson@eu.citrix.com, george.dunlap@citrix.com,
	xen-devel@lists.xenproject.org,
	Stefano Stabellini <stefano.stabellini@xilinx.com>
Subject: Re: [PATCH 04/14] kernel-doc: public/event_channel.h
Date: Fri, 7 Aug 2020 14:51:17 -0700 (PDT)	[thread overview]
Message-ID: <alpine.DEB.2.21.2008071212590.16004@sstabellini-ThinkPad-T480s> (raw)
In-Reply-To: <57b251fc-8997-48b8-693c-08e38d643fc3@suse.com>

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.