docs(forge): add AX usage examples to core API

Co-Authored-By: Virgil <virgil@lethean.io>

client.go

@@ -27,6 +27,11 @@ type APIError struct {
 	URL        string
 }
 
+// Error returns the formatted Forge API error string.
+//
+// Usage:
+//
+//	err := (&forge.APIError{StatusCode: 404, Message: "not found", URL: "/api/v1/repos/x/y"}).Error()
 func (e *APIError) Error() string {
 	return core.Concat("forge: ", e.URL, " ", strconv.Itoa(e.StatusCode), ": ", e.Message)
 }
@@ -119,11 +124,19 @@ type Client struct {
 }
 
 // BaseURL returns the configured Forgejo base URL.
+//
+// Usage:
+//
+//	baseURL := client.BaseURL()
 func (c *Client) BaseURL() string {
 	return c.baseURL
 }
 
 // RateLimit returns the last known rate limit information.
+//
+// Usage:
+//
+//	rl := client.RateLimit()
 func (c *Client) RateLimit() RateLimit {
 	return c.rateLimit
 }
@@ -152,36 +165,64 @@ func NewClient(url, token string, opts ...Option) *Client {
 }
 
 // Get performs a GET request.
+//
+// Usage:
+//
+//	var out map[string]string
+//	err := client.Get(ctx, "/api/v1/user", &out)
 func (c *Client) Get(ctx context.Context, path string, out any) error {
 	_, err := c.doJSON(ctx, http.MethodGet, path, nil, out)
 	return err
 }
 
 // Post performs a POST request.
+//
+// Usage:
+//
+//	var out map[string]any
+//	err := client.Post(ctx, "/api/v1/orgs/core/repos", body, &out)
 func (c *Client) Post(ctx context.Context, path string, body, out any) error {
 	_, err := c.doJSON(ctx, http.MethodPost, path, body, out)
 	return err
 }
 
 // Patch performs a PATCH request.
+//
+// Usage:
+//
+//	var out map[string]any
+//	err := client.Patch(ctx, "/api/v1/repos/core/go-forge", body, &out)
 func (c *Client) Patch(ctx context.Context, path string, body, out any) error {
 	_, err := c.doJSON(ctx, http.MethodPatch, path, body, out)
 	return err
 }
 
 // Put performs a PUT request.
+//
+// Usage:
+//
+//	var out map[string]any
+//	err := client.Put(ctx, "/api/v1/repos/core/go-forge", body, &out)
 func (c *Client) Put(ctx context.Context, path string, body, out any) error {
 	_, err := c.doJSON(ctx, http.MethodPut, path, body, out)
 	return err
 }
 
 // Delete performs a DELETE request.
+//
+// Usage:
+//
+//	err := client.Delete(ctx, "/api/v1/repos/core/go-forge")
 func (c *Client) Delete(ctx context.Context, path string) error {
 	_, err := c.doJSON(ctx, http.MethodDelete, path, nil, nil)
 	return err
 }
 
 // DeleteWithBody performs a DELETE request with a JSON body.
+//
+// Usage:
+//
+//	err := client.DeleteWithBody(ctx, "/api/v1/repos/core/go-forge/labels", body)
 func (c *Client) DeleteWithBody(ctx context.Context, path string, body any) error {
 	_, err := c.doJSON(ctx, http.MethodDelete, path, body, nil)
 	return err
@@ -190,6 +231,10 @@ func (c *Client) DeleteWithBody(ctx context.Context, path string, body any) erro
 // PostRaw performs a POST request with a JSON body and returns the raw
 // response body as bytes instead of JSON-decoding. Useful for endpoints
 // such as /markdown that return raw HTML text.
+//
+// Usage:
+//
+//	body, err := client.PostRaw(ctx, "/api/v1/markdown", payload)
 func (c *Client) PostRaw(ctx context.Context, path string, body any) ([]byte, error) {
 	return c.postRawJSON(ctx, path, body)
 }
@@ -339,6 +384,10 @@ func (c *Client) postMultipartJSON(ctx context.Context, path string, query map[s
 
 // GetRaw performs a GET request and returns the raw response body as bytes
 // instead of JSON-decoding. Useful for endpoints that return raw file content.
+//
+// Usage:
+//
+//	body, err := client.GetRaw(ctx, "/api/v1/signing-key.gpg")
 func (c *Client) GetRaw(ctx context.Context, path string) ([]byte, error) {
 	url := c.baseURL + path
 

forge.go

@@ -64,4 +64,8 @@ func NewForge(url, token string, opts ...Option) *Forge {
 }
 
 // Client returns the underlying HTTP client.
+//
+// Usage:
+//
+//	client := f.Client()
 func (f *Forge) Client() *Client { return f.client }

resource.go

@@ -42,21 +42,39 @@ func NewResource[T any, C any, U any](c *Client, path string) *Resource[T, C, U]
 }
 
 // List returns a single page of resources.
+//
+// Usage:
+//
+//	page, err := res.List(ctx, forge.Params{"owner": "core"}, forge.DefaultList)
 func (r *Resource[T, C, U]) List(ctx context.Context, params Params, opts ListOptions) (*PagedResult[T], error) {
 	return ListPage[T](ctx, r.client, ResolvePath(r.collection, params), nil, opts)
 }
 
 // ListAll returns all resources across all pages.
+//
+// Usage:
+//
+//	items, err := res.ListAll(ctx, forge.Params{"owner": "core"})
 func (r *Resource[T, C, U]) ListAll(ctx context.Context, params Params) ([]T, error) {
 	return ListAll[T](ctx, r.client, ResolvePath(r.collection, params), nil)
 }
 
 // Iter returns an iterator over all resources across all pages.
+//
+// Usage:
+//
+//	for item, err := range res.Iter(ctx, forge.Params{"owner": "core"}) {
+//	    _, _ = item, err
+//	}
 func (r *Resource[T, C, U]) Iter(ctx context.Context, params Params) iter.Seq2[T, error] {
 	return ListIter[T](ctx, r.client, ResolvePath(r.collection, params), nil)
 }
 
 // Get returns a single resource by appending id to the path.
+//
+// Usage:
+//
+//	item, err := res.Get(ctx, forge.Params{"owner": "core", "repo": "go-forge"})
 func (r *Resource[T, C, U]) Get(ctx context.Context, params Params) (*T, error) {
 	var out T
 	if err := r.client.Get(ctx, ResolvePath(r.path, params), &out); err != nil {
@@ -66,6 +84,10 @@ func (r *Resource[T, C, U]) Get(ctx context.Context, params Params) (*T, error)
 }
 
 // Create creates a new resource.
+//
+// Usage:
+//
+//	item, err := res.Create(ctx, forge.Params{"owner": "core"}, body)
 func (r *Resource[T, C, U]) Create(ctx context.Context, params Params, body *C) (*T, error) {
 	var out T
 	if err := r.client.Post(ctx, ResolvePath(r.collection, params), body, &out); err != nil {
@@ -75,6 +97,10 @@ func (r *Resource[T, C, U]) Create(ctx context.Context, params Params, body *C)
 }
 
 // Update modifies an existing resource.
+//
+// Usage:
+//
+//	item, err := res.Update(ctx, forge.Params{"owner": "core", "repo": "go-forge"}, body)
 func (r *Resource[T, C, U]) Update(ctx context.Context, params Params, body *U) (*T, error) {
 	var out T
 	if err := r.client.Patch(ctx, ResolvePath(r.path, params), body, &out); err != nil {
@@ -84,6 +110,10 @@ func (r *Resource[T, C, U]) Update(ctx context.Context, params Params, body *U)
 }
 
 // Delete removes a resource.
+//
+// Usage:
+//
+//	err := res.Delete(ctx, forge.Params{"owner": "core", "repo": "go-forge"})
 func (r *Resource[T, C, U]) Delete(ctx context.Context, params Params) error {
 	return r.client.Delete(ctx, ResolvePath(r.path, params))
 }