docs(forge): add usage examples to option types

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

admin.go

@@ -23,6 +23,10 @@ type AdminService struct {
 }
 
 // AdminActionsRunListOptions controls filtering for admin Actions run listings.
+//
+// Usage:
+//
+//	opts := forge.AdminActionsRunListOptions{Event: "push", Status: "success"}
 type AdminActionsRunListOptions struct {
 	Event   string
 	Branch  string
@@ -55,6 +59,10 @@ func (o AdminActionsRunListOptions) queryParams() map[string]string {
 }
 
 // AdminUnadoptedListOptions controls filtering for unadopted repository listings.
+//
+// Usage:
+//
+//	opts := forge.AdminUnadoptedListOptions{Pattern: "core/*"}
 type AdminUnadoptedListOptions struct {
 	Pattern string
 }

issues.go

@@ -22,12 +22,20 @@ type IssueService struct {
 }
 
 // AttachmentUploadOptions controls metadata sent when uploading an attachment.
+//
+// Usage:
+//
+//	opts := forge.AttachmentUploadOptions{Name: "screenshot.png"}
 type AttachmentUploadOptions struct {
 	Name      string
 	UpdatedAt *time.Time
 }
 
 // RepoCommentListOptions controls filtering for repository-wide issue comment listings.
+//
+// Usage:
+//
+//	opts := forge.RepoCommentListOptions{Page: 1, Limit: 50}
 type RepoCommentListOptions struct {
 	Since  *time.Time
 	Before *time.Time
@@ -56,6 +64,10 @@ func newIssueService(c *Client) *IssueService {
 }
 
 // SearchIssuesOptions controls filtering for the global issue search endpoint.
+//
+// Usage:
+//
+//	opts := forge.SearchIssuesOptions{State: "open"}
 type SearchIssuesOptions struct {
 	State           string
 	Labels          string

milestones.go

@@ -8,6 +8,10 @@ import (
 )
 
 // MilestoneListOptions controls filtering for repository milestone listings.
+//
+// Usage:
+//
+//	opts := forge.MilestoneListOptions{State: "open"}
 type MilestoneListOptions struct {
 	State string
 	Name  string

notifications.go

@@ -12,6 +12,10 @@ import (
 )
 
 // NotificationListOptions controls filtering for notification listings.
+//
+// Usage:
+//
+//	opts := forge.NotificationListOptions{All: true, StatusTypes: []string{"unread"}}
 type NotificationListOptions struct {
 	All          bool
 	StatusTypes  []string
@@ -54,6 +58,10 @@ type NotificationService struct {
 }
 
 // NotificationRepoMarkOptions controls how repository notifications are marked.
+//
+// Usage:
+//
+//	opts := forge.NotificationRepoMarkOptions{All: true, ToStatus: "read"}
 type NotificationRepoMarkOptions struct {
 	All         bool
 	StatusTypes []string
@@ -62,6 +70,10 @@ type NotificationRepoMarkOptions struct {
 }
 
 // NotificationMarkOptions controls how authenticated-user notifications are marked.
+//
+// Usage:
+//
+//	opts := forge.NotificationMarkOptions{All: true, ToStatus: "read"}
 type NotificationMarkOptions struct {
 	All         bool
 	StatusTypes []string

orgs.go

@@ -20,6 +20,10 @@ type OrgService struct {
 }
 
 // OrgActivityFeedListOptions controls filtering for organisation activity feeds.
+//
+// Usage:
+//
+//	opts := forge.OrgActivityFeedListOptions{Date: &day}
 type OrgActivityFeedListOptions struct {
 	Date *time.Time
 }

releases.go

@@ -20,6 +20,10 @@ type ReleaseService struct {
 }
 
 // ReleaseAttachmentUploadOptions controls metadata sent when uploading a release attachment.
+//
+// Usage:
+//
+//	opts := forge.ReleaseAttachmentUploadOptions{Name: "release.zip"}
 type ReleaseAttachmentUploadOptions struct {
 	Name        string
 	ExternalURL string

repos.go

@@ -22,6 +22,10 @@ type RepoService struct {
 }
 
 // RepoKeyListOptions controls filtering for repository key listings.
+//
+// Usage:
+//
+//	opts := forge.RepoKeyListOptions{Fingerprint: "AB:CD"}
 type RepoKeyListOptions struct {
 	KeyID       int64
 	Fingerprint string
@@ -42,6 +46,10 @@ func (o RepoKeyListOptions) queryParams() map[string]string {
 }
 
 // ActivityFeedListOptions controls filtering for repository activity feeds.
+//
+// Usage:
+//
+//	opts := forge.ActivityFeedListOptions{Date: &day}
 type ActivityFeedListOptions struct {
 	Date *time.Time
 }
@@ -56,6 +64,10 @@ func (o ActivityFeedListOptions) queryParams() map[string]string {
 }
 
 // RepoTimeListOptions controls filtering for repository tracked times.
+//
+// Usage:
+//
+//	opts := forge.RepoTimeListOptions{User: "alice"}
 type RepoTimeListOptions struct {
 	User   string
 	Since  *time.Time

users.go

@@ -21,6 +21,10 @@ type UserService struct {
 }
 
 // UserSearchOptions controls filtering for user searches.
+//
+// Usage:
+//
+//	opts := forge.UserSearchOptions{UID: 1001}
 type UserSearchOptions struct {
 	UID int64
 }
@@ -35,6 +39,10 @@ func (o UserSearchOptions) queryParams() map[string]string {
 }
 
 // UserKeyListOptions controls filtering for authenticated user public key listings.
+//
+// Usage:
+//
+//	opts := forge.UserKeyListOptions{Fingerprint: "AB:CD"}
 type UserKeyListOptions struct {
 	Fingerprint string
 }