Minor syntax improvements for //kok:param

[RussellLuo]

Syntax improvements

Original syntax (after #18):

• //kok:param <argName> [<parameter> [; <parameter2> [; ...]]]
  • parameter: in=<in> name=<name> required=<required> type=<type> descr=<descr>

New syntax:

• //kok:param <argName> [<parameter> [, <parameter2> [, ...]]]
  • parameter: in=<in> name=<name> required=<required> type=<type> descr=<descr>
• NOTE: If multiple method arguments are involved, you may need to apply multiple bindings. This can be done by adding a new //kok:param directive, or by appending the binding to the end of the last //kok:param directive in a semicolon-separated list.

Example

After the above syntax improvements, here are the equivalent annotations:

One binding per //kok:param

type Service interface {
    //kok:op POST /users
    //kok:param name
    //kok:param age in=query
    //kok:param ip in=header name=X-Forwarded-For, in=request name=RemoteAddr
    CreateUser(ctx context.Context, name string, age int, ip net.IP) (err error)
}

// HTTP request:
// $ http POST /users?name=tracey&age=1

Multiple bindings in a single //kok:param

type Service interface {
    //kok:op POST /users
    //kok:param name; age in=query; ip in=header name=X-Forwarded-For, in=request name=RemoteAddr
    CreateUser(ctx context.Context, name string, age int, ip net.IP) (err error)
}

// HTTP request:
// $ http POST /users?name=tracey&age=1

Multiple bindings in a single //kok:param (but using backslash for better readability)

type Service interface {
    //kok:op POST /users
    //kok:param name; \
    //          age in=query; \
    //          ip in=header name=X-Forwarded-For, in=request name=RemoteAddr
    CreateUser(ctx context.Context, name string, age int, ip net.IP) (err error)
}

// HTTP request:
// $ http POST /users?name=tracey&age=1