Re: [Nbd] [PATCH v4 1/2] doc: Use sequence of replies for NBD_OPT_INFO/GO

[Wouter Verhelst <w@...112...>]

Hi,

On Thu, Apr 14, 2016 at 09:09:19PM -0600, Eric Blake wrote:
[...]
>      The reply to an `NBD_OPT_GO` is identical to the reply to `NBD_OPT_INFO`
> -    save that if the reply indicates success (i.e. is `NBD_REP_SERVER`),
> +    save that if the reply indicates success (i.e. ends with `NBD_REP_ACK`),
>      the client and the server both immediately enter the transmission
>      phase. The server MUST NOT send any zero padding bytes after the
> -    `NBD_REP_SERVER` data, whether or not the client negotiated the
> +    `NBD_REP_ACK` data, whether or not the client negotiated the
>      `NBD_FLAG_C_NO_ZEROES` flag. After sending this reply the server MUST
>      immediately move to the transmission phase, and after receiving this
>      reply, the client MUST immediately move to the transmission phase;
>      therefore, the server MUST NOT send this particular reply until all
>      other pending option replies have been sent by the server.

Rereading this, the second half of this paragraph feels a bit verbose. It might
be useful to revisit it at some point (not necessarily now, though!)

> +* `NBD_REP_INFO`
> +
> +    A detailed description about an aspect of an export.  The response
> +    to `NBD_OPT_INFO` and `NBD_OPT_GO` includes zero or more of these
> +    messages prior to a final error reply, or at least one before an
> +    `NBD_REP_ACK` reply indicating success.  The `NBD_INFO_EXPORT`
> +    type is mandatory prior to success, so that `NBD_OPT_GO` can
> +    provide a superset of the information given in response to
> +    `NBD_OPT_EXPORT_NAME`; all other types are optional.  A particular
> +    information type SHOULD only appear once for a given export unless
> +    documented otherwise.
> +
> +    Clients MUST NOT rely on any particular ordering amongst the
> +    `NBD_OPT_INFO` replies, and MUST ignore information types that it
> +    does not recognize.

Grammar nit: Either make the "it" at the end of the second line be plural form,
or the "clients" at the start of the sentence be "a client".

Other than that, looks good.

[...]

-- 
< ron> I mean, the main *practical* problem with C++, is there's like a dozen
       people in the world who think they really understand all of its rules,
       and pretty much all of them are just lying to themselves too.
 -- #debian-devel, OFTC, 2016-02-12