Skip to content

Commit

Permalink
docs: refine comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@aofei
aofei committed Jul 3, 2020
1 parent 1caa339 commit 69682cc
Show file tree
Hide file tree
Showing 4 changed files with 37 additions and 53 deletions.
60 changes: 24 additions & 36 deletions air.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,11 @@ framework, registering a route usually requires at least two params:
The first param is a route path that contains 6 components. Among them, "users",
"posts" and "assets" are STATIC components, ":UserID" and ":PostID" are PARAM
components, "*" is an ANY component. Note that all route params (PARAM
component(s) and ANY component) will be parsed into the `Request` and can be
accessed via the `Request.Param` and `Request.Params`. The name of a
`RequestParam` parsed from a PARAM component always discards its leading ":",
such as ":UserID" will become "UserID". The name of a `RequestParam` parsed from
an ANY component is "*".
components, "*" is an ANY component. Note that all route params (PARAM and ANY
components) will be parsed into the `Request` and can be accessed via the
`Request.Param` and `Request.Params`. The name of a `RequestParam` parsed from a
PARAM component always discards its leading ":", such as ":UserID" will become
"UserID". The name of a `RequestParam` parsed from an ANY component is "*".
The second param is a `Handler` that serves the requests that match this route.
*/
Expand Down Expand Up @@ -159,9 +158,9 @@ type Air struct {
// Default value: 0
IdleTimeout time.Duration `mapstructure:"idle_timeout"`

// MaxHeaderBytes is the maximum number of bytes the server will read
// parsing the request headers' names and values, including the HTTP/1.x
// Request-Line.
// MaxHeaderBytes is the maximum number of bytes allowed for the server
// to read parsing the request headers' names and values, including
// HTTP/1.x request-line.
//
// Default value: 1048576
MaxHeaderBytes int `mapstructure:"max_header_bytes"`
Expand Down Expand Up @@ -692,8 +691,7 @@ func New() *Air {
// GET registers a new GET route for the path with the matching h in the router
// of the a with the optional route-level gases.
//
// The path may consist of STATIC component(s), PARAM component(s) and ANY
// component.
// The path may consist of STATIC, PARAM and ANY components.
//
// The gases is always FILO.
func (a *Air) GET(path string, h Handler, gases ...Gas) {
Expand All @@ -703,19 +701,17 @@ func (a *Air) GET(path string, h Handler, gases ...Gas) {
// HEAD registers a new HEAD route for the path with the matching h in the
// router of the a with the optional route-level gases.
//
// The path may consist of STATIC component(s), PARAM component(s) and ANY
// component.
// The path may consist of STATIC, PARAM and ANY components.
//
// The way, the gases is always FILO.
// The gases is always FILO.
func (a *Air) HEAD(path string, h Handler, gases ...Gas) {
a.router.register(http.MethodHead, path, h, gases...)
}

// POST registers a new POST route for the path with the matching h in the
// router of the a with the optional route-level gases.
//
// The path may consist of STATIC component(s), PARAM component(s) and ANY
// component.
// The path may consist of STATIC, PARAM and ANY components.
//
// The gases is always FILO.
func (a *Air) POST(path string, h Handler, gases ...Gas) {
Expand All @@ -725,8 +721,7 @@ func (a *Air) POST(path string, h Handler, gases ...Gas) {
// PUT registers a new PUT route for the path with the matching h in the router
// of the a with the optional route-level gases.
//
// The path may consist of STATIC component(s), PARAM component(s) and ANY
// component.
// The path may consist of STATIC, PARAM and ANY components.
//
// The gases is always FILO.
func (a *Air) PUT(path string, h Handler, gases ...Gas) {
Expand All @@ -736,8 +731,7 @@ func (a *Air) PUT(path string, h Handler, gases ...Gas) {
// PATCH registers a new PATCH route for the path with the matching h in the
// router of the a with the optional route-level gases.
//
// The path may consist of STATIC component(s), PARAM component(s) and ANY
// component.
// The path may consist of STATIC, PARAM and ANY components.
//
// The gases is always FILO.
func (a *Air) PATCH(path string, h Handler, gases ...Gas) {
Expand All @@ -747,8 +741,7 @@ func (a *Air) PATCH(path string, h Handler, gases ...Gas) {
// DELETE registers a new DELETE route for the path with the matching h in the
// router of the a with the optional route-level gases.
//
// The path may consist of STATIC component(s), PARAM component(s) and ANY
// component.
// The path may consist of STATIC, PARAM and ANY components.
//
// The gases is always FILO.
func (a *Air) DELETE(path string, h Handler, gases ...Gas) {
Expand All @@ -758,8 +751,7 @@ func (a *Air) DELETE(path string, h Handler, gases ...Gas) {
// CONNECT registers a new CONNECT route for the path with the matching h in the
// router of the a with the optional route-level gases.
//
// The path may consist of STATIC component(s), PARAM component(s) and ANY
// component.
// The path may consist of STATIC, PARAM and ANY components.
//
// The gases is always FILO.
func (a *Air) CONNECT(path string, h Handler, gases ...Gas) {
Expand All @@ -769,8 +761,7 @@ func (a *Air) CONNECT(path string, h Handler, gases ...Gas) {
// OPTIONS registers a new OPTIONS route for the path with the matching h in the
// router of the a with the optional route-level gases.
//
// The path may consist of STATIC component(s), PARAM component(s) and ANY
// component.
// The path may consist of STATIC, PARAM and ANY components.
//
// The gases is always FILO.
func (a *Air) OPTIONS(path string, h Handler, gases ...Gas) {
Expand All @@ -780,8 +771,7 @@ func (a *Air) OPTIONS(path string, h Handler, gases ...Gas) {
// TRACE registers a new TRACE route for the path with the matching h in the
// router of the a with the optional route-level gases.
//
// The path may consist of STATIC component(s), PARAM component(s) and ANY
// component.
// The path may consist of STATIC, PARAM and ANY components.
//
// The gases is always FILO.
func (a *Air) TRACE(path string, h Handler, gases ...Gas) {
Expand All @@ -795,8 +785,7 @@ func (a *Air) TRACE(path string, h Handler, gases ...Gas) {
// "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "CONNECT", "OPTIONS" and
// "TRACE". Invalid methods will be silently ignored.
//
// The path may consist of STATIC component(s), PARAM component(s) and ANY
// component.
// The path may consist of STATIC, PARAM and ANY components.
//
// The gases is always FILO.
func (a *Air) BATCH(methods []string, path string, h Handler, gases ...Gas) {
Expand Down Expand Up @@ -842,8 +831,7 @@ func (a *Air) BATCH(methods []string, path string, h Handler, gases ...Gas) {
// the a to serve a static file with the filename and optional route-level
// gases.
//
// The path may consist of STATIC component(s), PARAM component(s) and ANY
// component.
// The path may consist of STATIC, PARAM and ANY components.
//
// The gases is always FILO.
func (a *Air) FILE(path, filename string, gases ...Gas) {
Expand All @@ -863,8 +851,8 @@ func (a *Air) FILE(path, filename string, gases ...Gas) {
// router of the a to serve the static files from the root with the optional
// route-level gases.
//
// The path prefix may consits of STATIC component(s) and PARAM component(s).
// But it must not contain an ANY component.
// The prefix may consit of STATIC and PARAM components, but it must not contain
// ANY component.
//
// The gases is always FILO.
func (a *Air) FILES(prefix, root string, gases ...Gas) {
Expand Down Expand Up @@ -897,8 +885,8 @@ func (a *Air) FILES(prefix, root string, gases ...Gas) {
// Group returns a new instance of the `Group` with the path prefix and optional
// group-level gases that inherited from the a.
//
// The path prefix may consits of STATIC component(s) and param component(s).
// But it must not contain an ANY component.
// The prefix may consit of STATIC and PARAM components, but it must not contain
// ANY component.
//
// The gases is always FILO.
func (a *Air) Group(prefix string, gases ...Gas) *Group {
Expand Down
4 changes: 2 additions & 2 deletions group.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ type Group struct {
//
// All paths of routes registered by the group will share the `Prefix`.
//
// The `Prefix` may consits of STATIC component(s) and PARAM
// component(s), but it must not contain an ANY component.
// The `Prefix` may consit of STATIC and PARAM components, but it must
// not contain ANY component.
Prefix string

// Gases is the group-level gases.
Expand Down
18 changes: 8 additions & 10 deletions request.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ type Request struct {
//
// See RFC 7231, section 4.3.
//
// For HTTP/1.x, it is from the Request-Line.
// For HTTP/1.x, it is from the request-line.
//
// For HTTP/2, it is from the ":method" pseudo-header.
//
Expand All @@ -37,7 +37,7 @@ type Request struct {
//
// See RFC 3986, section 3.1.
//
// For HTTP/1.x, it is from the Request-Line.
// For HTTP/1.x, it is from the request-line.
//
// For HTTP/2, it is from the ":scheme" pseudo-header.
//
Expand All @@ -55,14 +55,13 @@ type Request struct {
// E.g.: "localhost:8080"
Authority string

// Path is the path. Note that it contains the query part (anyway, the
// HTTP/2 specification says so).
// Path is the path. It may contain the query part.
//
// For HTTP/1.x, it represents the request-target of the Request-Line.
// See RFC 7230, section 3.1.1.
// See RFC 7540, section 8.1.2.3.
//
// For HTTP/2, it represents the ":path" pseudo-header. See RFC 7540,
// section 8.1.2.3.
// For HTTP/1.x, it represents the request-target of the request-line.
//
// For HTTP/2, it represents the ":path" pseudo-header.
//
// E.g.: "/foo/bar?foo=bar"
Path string
Expand All @@ -78,8 +77,7 @@ type Request struct {
// The `Header` is basically the same for both HTTP/1.x and HTTP/2. The
// only difference is that HTTP/2 requires header names to be lowercase
// (for aesthetic reasons, this framework decided to follow this rule
// implicitly, so please use the header name in the HTTP/1.x way). See
// RFC 7540, section 8.1.2.
// implicitly, so please use the header name in HTTP/1.x style).
//
// E.g.: {"Foo": ["bar"]}
Header http.Header
Expand Down
8 changes: 3 additions & 5 deletions response.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,7 @@ type Response struct {
// The `Header` is basically the same for both HTTP/1.x and HTTP/2. The
// only difference is that HTTP/2 requires header names to be lowercase
// (for aesthetic reasons, this framework decided to follow this rule
// implicitly, so please use the header name in the HTTP/1.x way). See
// RFC 7540, section 8.1.2.
// implicitly, so please use the header name in HTTP/1.x style).
//
// E.g.: {"Foo": ["bar"]}
Header http.Header
Expand Down Expand Up @@ -827,9 +826,8 @@ type ReverseProxy struct {

// ModifyRequestPath modifies the path of the request to the target.
//
// Note that the path contains the query part (anyway, the HTTP/2
// specification says so). Therefore, the returned path must also be in
// this format.
// Note that the path contains the query part. Therefore, the returned
// path must also be in this format.
ModifyRequestPath func(path string) (string, error)

// ModifyRequestHeader modifies the header of the request to the target.
Expand Down

0 comments on commit 69682cc

Please sign in to comment.