From 2a18ca7b8354eb300e5bbf7d4873b56125dea832 Mon Sep 17 00:00:00 2001 From: Spiegel Date: Sat, 9 May 2026 21:50:27 +0900 Subject: [PATCH] docs: improve API comments and update copyright years --- client.go | 26 ++++++++++++++++---------- errors.go | 12 ++++++++---- fetch.go | 23 ++++++++++++++++++----- response.go | 7 ++++--- url.go | 6 ++++-- 5 files changed, 50 insertions(+), 24 deletions(-) diff --git a/client.go b/client.go index 1c74b32..259fa55 100644 --- a/client.go +++ b/client.go @@ -17,9 +17,10 @@ type client struct { client *http.Client } +// ClientOpts configures a Client. type ClientOpts func(*client) -// New function returns Client instance. +// New creates a new Client. func New(opts ...ClientOpts) Client { cli := &client{client: &http.Client{}} for _, opt := range opts { @@ -28,7 +29,9 @@ func New(opts ...ClientOpts) Client { return cli } -// WithProtocol returns function for setting http.Client. +// WithHTTPClient sets the HTTP client used by fetch. +// +// If cli is nil, it falls back to a default *http.Client. func WithHTTPClient(cli *http.Client) ClientOpts { return func(c *client) { if cli == nil { @@ -39,13 +42,13 @@ func WithHTTPClient(cli *http.Client) ClientOpts { } } -// Get method returns respons data from URL by GET method. -// Deprecated: Should use GetWithContext() method instead of Get() method. +// Get fetches data from URL with HTTP GET. +// Deprecated: Use GetWithContext instead. func (c *client) Get(u *url.URL, opts ...RequestOpts) (Response, error) { return c.GetWithContext(context.Background(), u, opts...) } -// GetWithContext method returns respons data from URL by GET method with context.Context. +// GetWithContext fetches data from URL with HTTP GET and context. func (c *client) GetWithContext(ctx context.Context, u *url.URL, opts ...RequestOpts) (Response, error) { req, err := request(ctx, http.MethodGet, u, nil, opts...) if err != nil { @@ -61,13 +64,13 @@ func (c *client) GetWithContext(ctx context.Context, u *url.URL, opts ...Request return resp, nil } -// Post method returns respons data from URL by POST method. -// Deprecated: Should use PostWithContext() method instead of Post() method. +// Post fetches data from URL with HTTP POST. +// Deprecated: Use PostWithContext instead. func (c *client) Post(u *url.URL, payload io.Reader, opts ...RequestOpts) (Response, error) { return c.PostWithContext(context.Background(), u, payload, opts...) } -// PostWithContext method returns respons data from URL by POST method with context.Context. +// PostWithContext fetches data from URL with HTTP POST and context. func (c *client) PostWithContext(ctx context.Context, u *url.URL, payload io.Reader, opts ...RequestOpts) (Response, error) { req, err := request(ctx, http.MethodPost, u, payload, opts...) if err != nil { @@ -83,8 +86,8 @@ func (c *client) PostWithContext(ctx context.Context, u *url.URL, payload io.Rea return resp, nil } -// WithProtocol returns function for setting context.Context. -// Deprecated: should not be used +// WithContext sets request context on an option-applied request. +// Deprecated: Use GetWithContext and PostWithContext instead. func WithContext(ctx context.Context) RequestOpts { return func(req *http.Request) *http.Request { if ctx != nil { @@ -110,6 +113,7 @@ func WithRequestHeaderSet(name, value string) RequestOpts { } } +// request creates an HTTP request and applies request options. func request(ctx context.Context, method string, u *url.URL, payload io.Reader, opts ...RequestOpts) (*http.Request, error) { if u == nil { return nil, errs.Wrap(ErrInvalidURL) @@ -124,6 +128,7 @@ func request(ctx context.Context, method string, u *url.URL, payload io.Reader, return req, nil } +// fetch sends the request and validates response status. func (c *client) fetch(request *http.Request) (Response, error) { if c == nil { c = New().(*client) @@ -146,6 +151,7 @@ func (c *client) fetch(request *http.Request) (Response, error) { return resp, nil } +// urlText returns a string form of URL, or an empty string for nil URL. func urlText(u *url.URL) string { if u == nil { return "" diff --git a/errors.go b/errors.go index b618b26..5eb384b 100644 --- a/errors.go +++ b/errors.go @@ -3,13 +3,17 @@ package fetch import "errors" var ( - ErrNullPointer = errors.New("null reference instance") + // ErrNullPointer indicates a nil receiver or nil embedded value access. + ErrNullPointer = errors.New("null reference instance") + // ErrInvalidRequest indicates a request construction or execution failure. ErrInvalidRequest = errors.New("invalid HTTP request") - ErrInvalidURL = errors.New("invalid URL") - ErrHTTPStatus = errors.New("bad HTTP status") + // ErrInvalidURL indicates an invalid URL input. + ErrInvalidURL = errors.New("invalid URL") + // ErrHTTPStatus indicates non-success HTTP status. + ErrHTTPStatus = errors.New("bad HTTP status") ) -/* Copyright 2021 Spiegel +/* Copyright 2021-2026 Spiegel * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. diff --git a/fetch.go b/fetch.go index a43bc94..d63f5f9 100644 --- a/fetch.go +++ b/fetch.go @@ -7,28 +7,41 @@ import ( "net/url" ) +// RequestOpts applies options to an HTTP request. +// +// The returned request value allows option functions to replace the request, +// for example when changing context with req.WithContext. type RequestOpts func(*http.Request) *http.Request -// Client is inteface class for HTTP client. +// Client represents a fetch client. type Client interface { - // Deprecated: Should use GetWithContext() method instead of Get() method. + // Get sends a GET request. + // Deprecated: Use GetWithContext instead. Get(u *url.URL, opts ...RequestOpts) (Response, error) + // GetWithContext sends a GET request with context. GetWithContext(ctx context.Context, u *url.URL, opts ...RequestOpts) (Response, error) - // Deprecated: Should use PostWithContext() method instead of Post() method. + // Post sends a POST request. + // Deprecated: Use PostWithContext instead. Post(u *url.URL, payload io.Reader, opts ...RequestOpts) (Response, error) + // PostWithContext sends a POST request with context. PostWithContext(ctx context.Context, u *url.URL, payload io.Reader, opts ...RequestOpts) (Response, error) } -// Response is inteface class for HTTP response. +// Response wraps an HTTP response. type Response interface { + // Request returns the original request. Request() *http.Request + // Header returns response headers. Header() http.Header + // Body returns the response body reader. Body() io.ReadCloser + // Close drains and closes the response body. Close() error + // DumpBodyAndClose reads all body bytes and closes the response body. DumpBodyAndClose() ([]byte, error) } -/* Copyright 2023-2025 Spiegel +/* Copyright 2023-2026 Spiegel * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. diff --git a/response.go b/response.go index d81dfb0..5619542 100644 --- a/response.go +++ b/response.go @@ -8,7 +8,7 @@ import ( "github.com/goark/errs" ) -// response is wrapper class of http.Response. +// response wraps http.Response. type response struct { *http.Response } @@ -29,7 +29,7 @@ func (resp *response) Header() http.Header { return resp.Response.Header } -// Header method returns Body element in http.Response. +// Body method returns Body element in http.Response. func (resp *response) Body() io.ReadCloser { if resp == nil || resp.Response == nil { return nil @@ -37,7 +37,7 @@ func (resp *response) Body() io.ReadCloser { return resp.Response.Body } -// Close method closes Response.Body safety. +// Close method safely drains and closes Response.Body. func (resp *response) Close() (err error) { if resp == nil || resp.Response == nil { return nil @@ -56,6 +56,7 @@ func (resp *response) Close() (err error) { return } +// DumpBodyAndClose reads all response body bytes and closes Response.Body. func (resp *response) DumpBodyAndClose() (b []byte, err error) { if resp == nil || resp.Response == nil { err = errs.Wrap(ErrNullPointer) diff --git a/url.go b/url.go index f2f21a4..61313b1 100644 --- a/url.go +++ b/url.go @@ -7,7 +7,9 @@ import ( "github.com/goark/errs" ) -// URL function returns url.URL instance from string. +// URL parses rawURL and returns *url.URL. +// +// Leading and trailing whitespaces are trimmed before parsing. func URL(rawURL string) (*url.URL, error) { u, err := url.Parse(strings.TrimSpace(rawURL)) if err != nil { @@ -16,7 +18,7 @@ func URL(rawURL string) (*url.URL, error) { return u, nil } -/* Copyright 2021 Spiegel +/* Copyright 2021-2026 Spiegel * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License.