docs(client): improve Godoc comments for exported functions

client/README.md

@@ -3,7 +3,7 @@ Miniflux API Client
 
 [![PkgGoDev](https://pkg.go.dev/badge/miniflux.app/v2/client)](https://pkg.go.dev/miniflux.app/v2/client)
 
-Client library for Miniflux REST API.
+Go client for the Miniflux REST API. It supports API tokens or basic authentication and mirrors the server endpoints closely.
 
 Installation
 ------------

client/client.go

@@ -334,14 +334,14 @@ func (c *Client) MarkAllAsReadContext(ctx context.Context, userID int64) error {
 	return err
 }
 
-// IntegrationsStatus fetches the integrations status for the logged user.
+// IntegrationsStatus fetches the integrations status for the signed-in user.
 func (c *Client) IntegrationsStatus() (bool, error) {
 	ctx, cancel := withDefaultTimeout()
 	defer cancel()
 	return c.IntegrationsStatusContext(ctx)
 }
 
-// IntegrationsStatusContext fetches the integrations status for the logged user.
+// IntegrationsStatusContext fetches the integrations status for the signed-in user.
 func (c *Client) IntegrationsStatusContext(ctx context.Context) (bool, error) {
 	body, err := c.request.Get(ctx, "/v1/integrations/status")
 	if err != nil {
@@ -360,7 +360,7 @@ func (c *Client) IntegrationsStatusContext(ctx context.Context) (bool, error) {
 	return response.HasIntegrations, nil
 }
 
-// Discover try to find subscriptions from a website.
+// Discover tries to find subscriptions on a website.
 func (c *Client) Discover(url string) (Subscriptions, error) {
 	ctx, cancel := withDefaultTimeout()
 	defer cancel()
@@ -383,14 +383,14 @@ func (c *Client) DiscoverContext(ctx context.Context, url string) (Subscriptions
 	return subscriptions, nil
 }
 
-// Categories gets the list of categories.
+// Categories retrieves the list of categories.
 func (c *Client) Categories() (Categories, error) {
 	ctx, cancel := withDefaultTimeout()
 	defer cancel()
 	return c.CategoriesContext(ctx)
 }
 
-// CategoriesContext gets the list of categories.
+// CategoriesContext retrieves the list of categories.
 func (c *Client) CategoriesContext(ctx context.Context) (Categories, error) {
 	body, err := c.request.Get(ctx, "/v1/categories")
 	if err != nil {
@@ -537,14 +537,14 @@ func (c *Client) MarkCategoryAsReadContext(ctx context.Context, categoryID int64
 	return err
 }
 
-// CategoryFeeds gets feeds of a category.
+// CategoryFeeds returns all feeds for a category.
 func (c *Client) CategoryFeeds(categoryID int64) (Feeds, error) {
 	ctx, cancel := withDefaultTimeout()
 	defer cancel()
 	return c.CategoryFeedsContext(ctx, categoryID)
 }
 
-// CategoryFeedsContext gets feeds of a category.
+// CategoryFeedsContext returns all feeds for a category.
 func (c *Client) CategoryFeedsContext(ctx context.Context, categoryID int64) (Feeds, error) {
 	body, err := c.request.Get(ctx, fmt.Sprintf("/v1/categories/%d/feeds", categoryID))
 	if err != nil {
@@ -608,14 +608,14 @@ func (c *Client) FeedsContext(ctx context.Context) (Feeds, error) {
 	return feeds, nil
 }
 
-// Export creates OPML file.
+// Export exports subscriptions as an OPML document.
 func (c *Client) Export() ([]byte, error) {
 	ctx, cancel := withDefaultTimeout()
 	defer cancel()
 	return c.ExportContext(ctx)
 }
 
-// ExportContext creates OPML file.
+// ExportContext exports subscriptions as an OPML document.
 func (c *Client) ExportContext(ctx context.Context) ([]byte, error) {
 	body, err := c.request.Get(ctx, "/v1/export")
 	if err != nil {
@@ -886,7 +886,7 @@ func (c *Client) EntryContext(ctx context.Context, entryID int64) (*Entry, error
 	return entry, nil
 }
 
-// Entries fetch entries.
+// Entries fetches entries using the given filter.
 func (c *Client) Entries(filter *Filter) (*EntryResultSet, error) {
 	ctx, cancel := withDefaultTimeout()
 	defer cancel()
@@ -911,7 +911,7 @@ func (c *Client) EntriesContext(ctx context.Context, filter *Filter) (*EntryResu
 	return &result, nil
 }
 
-// FeedEntries fetch feed entries.
+// FeedEntries fetches entries for a feed using the given filter.
 func (c *Client) FeedEntries(feedID int64, filter *Filter) (*EntryResultSet, error) {
 	ctx, cancel := withDefaultTimeout()
 	defer cancel()
@@ -936,7 +936,7 @@ func (c *Client) FeedEntriesContext(ctx context.Context, feedID int64, filter *F
 	return &result, nil
 }
 
-// CategoryEntries fetch entries of a category.
+// CategoryEntries fetches entries for a category using the given filter.
 func (c *Client) CategoryEntries(categoryID int64, filter *Filter) (*EntryResultSet, error) {
 	ctx, cancel := withDefaultTimeout()
 	defer cancel()
@@ -1002,7 +1002,7 @@ func (c *Client) UpdateEntryContext(ctx context.Context, entryID int64, entryCha
 	return entry, nil
 }
 
-// ToggleStarred toggles entry starred value.
+// ToggleStarred toggles the starred flag of an entry.
 func (c *Client) ToggleStarred(entryID int64) error {
 	ctx, cancel := withDefaultTimeout()
 	defer cancel()

client/doc.go

@@ -6,7 +6,7 @@ Package client implements a client library for the Miniflux REST API.
 
 # Examples
 
-This code snippet fetch the list of users:
+This example fetches the list of users:
 
 	import (
 		miniflux "miniflux.app/v2/client"
@@ -20,7 +20,7 @@ This code snippet fetch the list of users:
 	}
 	fmt.Println(users, err)
 
-This one discover subscriptions on a website:
+This example discovers subscriptions on a website:
 
 	subscriptions, err := client.Discover("https://example.org/")
 	if err != nil {

client/model.go

@@ -356,6 +356,7 @@ type APIKeyCreationRequest struct {
 	Description string `json:"description"`
 }
 
+// SetOptionalField returns a pointer to the given value so optional request fields can be marked as set.
 func SetOptionalField[T any](value T) *T {
 	return &value
 }