Upgrade golang to 1.25.1 and add descriptions for the swagger structs' fields (#35418)

Makefile

@@ -31,7 +31,7 @@ GOFUMPT_PACKAGE ?= mvdan.cc/gofumpt@v0.8.0
 GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.4.0
 GXZ_PACKAGE ?= github.com/ulikunitz/xz/cmd/gxz@v0.5.15
 MISSPELL_PACKAGE ?= github.com/golangci/misspell/cmd/misspell@v0.7.0
-SWAGGER_PACKAGE ?= github.com/go-swagger/go-swagger/cmd/swagger@v0.32.3
+SWAGGER_PACKAGE ?= github.com/go-swagger/go-swagger/cmd/swagger@717e3cb29becaaf00e56953556c6d80f8a01b286
 XGO_PACKAGE ?= src.techknowlogick.com/xgo@latest
 GO_LICENSES_PACKAGE ?= github.com/google/go-licenses@v1
 GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1

go.mod

@@ -1,6 +1,6 @@
 module code.gitea.io/gitea
 
-go 1.24.6
+go 1.25.1
 
 // rfc5280 said: "The serial number is an integer assigned by the CA to each certificate."
 // But some CAs use negative serial number, just relax the check. related:

modules/globallock/locker_test.go

@@ -105,15 +105,13 @@ func testLocker(t *testing.T, locker Locker) {
 		require.NoError(t, err)
 
 		wg := &sync.WaitGroup{}
-		wg.Add(1)
+		wg.Go(func() {
-		go func() {
-			defer wg.Done()
 			started := time.Now()
 			release, err := locker.Lock(t.Context(), "test") // should be blocked for seconds
 			defer release()
 			assert.Greater(t, time.Since(started), time.Second)
 			assert.NoError(t, err)
-		}()
+		})
 
 		time.Sleep(2 * time.Second)
 		release()

modules/log/event_writer_conn_test.go

@@ -62,11 +62,9 @@ func TestConnLogger(t *testing.T) {
 	}
 	expected := fmt.Sprintf("%s%s %s:%d:%s [%c] %s\n", prefix, dateString, event.Filename, event.Line, event.Caller, strings.ToUpper(event.Level.String())[0], event.MsgSimpleText)
 	var wg sync.WaitGroup
-	wg.Add(1)
+	wg.Go(func() {
-	go func() {
-		defer wg.Done()
 		listenReadAndClose(t, l, expected)
-	}()
+	})
 	logger.SendLogEvent(&event)
 	wg.Wait()
 

modules/queue/workergroup.go

@@ -153,11 +153,7 @@ func resetIdleTicker(t *time.Ticker, dur time.Duration) {
 
 // doStartNewWorker starts a new worker for the queue, the worker reads from worker's channel and handles the items.
 func (q *WorkerPoolQueue[T]) doStartNewWorker(wp *workerGroup[T]) {
-	wp.wg.Add(1)
+	wp.wg.Go(func() {
-
-	go func() {
-		defer wp.wg.Done()
-
 		log.Debug("Queue %q starts new worker", q.GetName())
 		defer log.Debug("Queue %q stops idle worker", q.GetName())
 
@@ -192,7 +188,7 @@ func (q *WorkerPoolQueue[T]) doStartNewWorker(wp *workerGroup[T]) {
 				q.workerNumMu.Unlock()
 			}
 		}
-	}()
+	})
 }
 
 // doFlush flushes the queue: it tries to read all items from the queue and handles them.

modules/structs/activity.go

@@ -6,20 +6,32 @@ package structs
 import "time"
 
 type Activity struct {
+	// The unique identifier of the activity
 	ID int64 `json:"id"`
+	// The ID of the user who receives/sees this activity
 	UserID int64 `json:"user_id"` // Receiver user
 	// the type of action
 	//
 	// enum: create_repo,rename_repo,star_repo,watch_repo,commit_repo,create_issue,create_pull_request,transfer_repo,push_tag,comment_issue,merge_pull_request,close_issue,reopen_issue,close_pull_request,reopen_pull_request,delete_tag,delete_branch,mirror_sync_push,mirror_sync_create,mirror_sync_delete,approve_pull_request,reject_pull_request,comment_pull,publish_release,pull_review_dismissed,pull_request_ready_for_review,auto_merge_pull_request
 	OpType string `json:"op_type"`
+	// The ID of the user who performed the action
 	ActUserID int64 `json:"act_user_id"`
+	// The user who performed the action
 	ActUser *User `json:"act_user"`
+	// The ID of the repository associated with the activity
 	RepoID int64 `json:"repo_id"`
+	// The repository associated with the activity
 	Repo *Repository `json:"repo"`
+	// The ID of the comment associated with the activity (if applicable)
 	CommentID int64 `json:"comment_id"`
+	// The comment associated with the activity (if applicable)
 	Comment *Comment `json:"comment"`
+	// The name of the git reference (branch/tag) associated with the activity
 	RefName string `json:"ref_name"`
+	// Whether this activity is from a private repository
 	IsPrivate bool `json:"is_private"`
+	// Additional content or details about the activity
 	Content string `json:"content"`
+	// The date and time when the activity occurred
 	Created time.Time `json:"created"`
 }

modules/structs/activitypub.go

@@ -5,5 +5,6 @@ package structs
 
 // ActivityPub type
 type ActivityPub struct {
+	// Context defines the JSON-LD context for ActivityPub
 	Context string `json:"@context"`
 }

modules/structs/admin_user.go

@@ -8,6 +8,7 @@ import "time"
 
 // CreateUserOption create user options
 type CreateUserOption struct {
+	// The authentication source ID to associate with the user
 	SourceID int64 `json:"source_id"`
 	// identifier of the user, provided by the external authenticator (if configured)
 	// default: empty
@@ -15,14 +16,20 @@ type CreateUserOption struct {
 	// username of the user
 	// required: true
 	Username string `json:"username" binding:"Required;Username;MaxSize(40)"`
+	// The full display name of the user
 	FullName string `json:"full_name" binding:"MaxSize(100)"`
 	// required: true
 	// swagger:strfmt email
 	Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
+	// The plain text password for the user
 	Password string `json:"password" binding:"MaxSize(255)"`
+	// Whether the user must change password on first login
 	MustChangePassword *bool `json:"must_change_password"`
+	// Whether to send welcome notification email to the user
 	SendNotify bool `json:"send_notify"`
+	// Whether the user has restricted access privileges
 	Restricted *bool `json:"restricted"`
+	// User visibility level: public, limited, or private
 	Visibility string `json:"visibility" binding:"In(,public,limited,private)"`
 
 	// For explicitly setting the user creation timestamp. Useful when users are
@@ -34,26 +41,43 @@ type CreateUserOption struct {
 // EditUserOption edit user options
 type EditUserOption struct {
 	// required: true
+	// The authentication source ID to associate with the user
 	SourceID int64 `json:"source_id"`
 	// identifier of the user, provided by the external authenticator (if configured)
 	// default: empty
 	// required: true
 	LoginName string `json:"login_name" binding:"Required"`
 	// swagger:strfmt email
+	// The email address of the user
 	Email *string `json:"email" binding:"MaxSize(254)"`
+	// The full display name of the user
 	FullName *string `json:"full_name" binding:"MaxSize(100)"`
+	// The plain text password for the user
 	Password string `json:"password" binding:"MaxSize(255)"`
+	// Whether the user must change password on next login
 	MustChangePassword *bool `json:"must_change_password"`
+	// The user's personal website URL
 	Website *string `json:"website" binding:"OmitEmpty;ValidUrl;MaxSize(255)"`
+	// The user's location or address
 	Location *string `json:"location" binding:"MaxSize(50)"`
+	// The user's personal description or bio
 	Description *string `json:"description" binding:"MaxSize(255)"`
+	// Whether the user account is active
 	Active *bool `json:"active"`
+	// Whether the user has administrator privileges
 	Admin *bool `json:"admin"`
+	// Whether the user can use Git hooks
 	AllowGitHook *bool `json:"allow_git_hook"`
+	// Whether the user can import local repositories
 	AllowImportLocal *bool `json:"allow_import_local"`
+	// Maximum number of repositories the user can create
 	MaxRepoCreation *int `json:"max_repo_creation"`
+	// Whether the user is prohibited from logging in
 	ProhibitLogin *bool `json:"prohibit_login"`
+	// Whether the user can create organizations
 	AllowCreateOrganization *bool `json:"allow_create_organization"`
+	// Whether the user has restricted access privileges
 	Restricted *bool `json:"restricted"`
+	// User visibility level: public, limited, or private
 	Visibility string `json:"visibility" binding:"In(,public,limited,private)"`
 }

modules/structs/attachment.go

@@ -10,18 +10,26 @@ import (
 // Attachment a generic attachment
 // swagger:model
 type Attachment struct {
+	// ID is the unique identifier for the attachment
 	ID int64 `json:"id"`
+	// Name is the filename of the attachment
 	Name string `json:"name"`
+	// Size is the file size in bytes
 	Size int64 `json:"size"`
+	// DownloadCount is the number of times the attachment has been downloaded
 	DownloadCount int64 `json:"download_count"`
 	// swagger:strfmt date-time
+	// Created is the time when the attachment was uploaded
 	Created time.Time `json:"created_at"`
+	// UUID is the unique identifier for the attachment file
 	UUID string `json:"uuid"`
+	// DownloadURL is the URL to download the attachment
 	DownloadURL string `json:"browser_download_url"`
 }
 
 // EditAttachmentOptions options for editing attachments
 // swagger:model
 type EditAttachmentOptions struct {
+	// Name is the new filename for the attachment
 	Name string `json:"name"`
 }

modules/structs/cron.go

@@ -7,9 +7,14 @@ import "time"
 
 // Cron represents a Cron task
 type Cron struct {
+	// The name of the cron task
 	Name string `json:"name"`
+	// The cron schedule expression (e.g., "0 0 * * *")
 	Schedule string `json:"schedule"`
+	// The next scheduled execution time
 	Next time.Time `json:"next"`
+	// The previous execution time
 	Prev time.Time `json:"prev"`
+	// The total number of times this cron task has been executed
 	ExecTimes int64 `json:"exec_times"`
 }

modules/structs/git_blob.go

@@ -5,12 +5,19 @@ package structs
 
 // GitBlobResponse represents a git blob
 type GitBlobResponse struct {
+	// The content of the git blob (may be base64 encoded)
 	Content *string `json:"content"`
+	// The encoding used for the content (e.g., "base64")
 	Encoding *string `json:"encoding"`
+	// The URL to access this git blob
 	URL string `json:"url"`
+	// The SHA hash of the git blob
 	SHA string `json:"sha"`
+	// The size of the git blob in bytes
 	Size int64 `json:"size"`
 
+	// The LFS object ID if this blob is stored in LFS
 	LfsOid *string `json:"lfs_oid,omitempty"`
+	// The size of the LFS object if this blob is stored in LFS
 	LfsSize *int64 `json:"lfs_size,omitempty"`
 }

modules/structs/git_hook.go

@@ -5,8 +5,11 @@ package structs
 
 // GitHook represents a Git repository hook
 type GitHook struct {
+	// Name is the name of the Git hook
 	Name string `json:"name"`
+	// IsActive indicates if the hook is active
 	IsActive bool `json:"is_active"`
+	// Content contains the script content of the hook
 	Content string `json:"content,omitempty"`
 }
 
@@ -15,5 +18,6 @@ type GitHookList []*GitHook
 
 // EditGitHookOption options when modifying one Git hook
 type EditGitHookOption struct {
+	// Content is the new script content for the hook
 	Content string `json:"content"`
 }

modules/structs/hook.go

@@ -17,17 +17,27 @@ var ErrInvalidReceiveHook = errors.New("Invalid JSON payload received over webho
 
 // Hook a hook is a web hook when one repository changed
 type Hook struct {
+	// The unique identifier of the webhook
 	ID int64 `json:"id"`
+	// The type of the webhook (e.g., gitea, slack, discord)
 	Type string `json:"type"`
+	// Branch filter pattern to determine which branches trigger the webhook
 	BranchFilter string `json:"branch_filter"`
+	// The URL of the webhook endpoint (hidden in JSON)
 	URL string `json:"-"`
+	// Configuration settings for the webhook
 	Config map[string]string `json:"config"`
+	// List of events that trigger this webhook
 	Events []string `json:"events"`
+	// Authorization header to include in webhook requests
 	AuthorizationHeader string `json:"authorization_header"`
+	// Whether the webhook is active and will be triggered
 	Active bool `json:"active"`
 	// swagger:strfmt date-time
+	// The date and time when the webhook was last updated
 	Updated time.Time `json:"updated_at"`
 	// swagger:strfmt date-time
+	// The date and time when the webhook was created
 	Created time.Time `json:"created_at"`
 }
 
@@ -42,22 +52,33 @@ type CreateHookOptionConfig map[string]string
 type CreateHookOption struct {
 	// required: true
 	// enum: dingtalk,discord,gitea,gogs,msteams,slack,telegram,feishu,wechatwork,packagist
+	// The type of the webhook to create
 	Type string `json:"type" binding:"Required"`
 	// required: true
+	// Configuration settings for the webhook
 	Config CreateHookOptionConfig `json:"config" binding:"Required"`
+	// List of events that will trigger this webhook
 	Events []string `json:"events"`
+	// Branch filter pattern to determine which branches trigger the webhook
 	BranchFilter string `json:"branch_filter" binding:"GlobPattern"`
+	// Authorization header to include in webhook requests
 	AuthorizationHeader string `json:"authorization_header"`
 	// default: false
+	// Whether the webhook should be active upon creation
 	Active bool `json:"active"`
 }
 
 // EditHookOption options when modify one hook
 type EditHookOption struct {
+	// Configuration settings for the webhook
 	Config map[string]string `json:"config"`
+	// List of events that trigger this webhook
 	Events []string `json:"events"`
+	// Branch filter pattern to determine which branches trigger the webhook
 	BranchFilter string `json:"branch_filter" binding:"GlobPattern"`
+	// Authorization header to include in webhook requests
 	AuthorizationHeader string `json:"authorization_header"`
+	// Whether the webhook is active and will be triggered
 	Active *bool `json:"active"`
 }
 
@@ -83,24 +104,38 @@ type PayloadUser struct {
 type PayloadCommit struct {
 	// sha1 hash of the commit
 	ID string `json:"id"`
+	// The commit message
 	Message string `json:"message"`
+	// The URL to view this commit
 	URL string `json:"url"`
+	// The author of the commit
 	Author *PayloadUser `json:"author"`
+	// The committer of the commit
 	Committer *PayloadUser `json:"committer"`
+	// GPG verification information for the commit
 	Verification *PayloadCommitVerification `json:"verification"`
 	// swagger:strfmt date-time
+	// The timestamp when the commit was made
 	Timestamp time.Time `json:"timestamp"`
+	// List of files added in this commit
 	Added []string `json:"added"`
+	// List of files removed in this commit
 	Removed []string `json:"removed"`
+	// List of files modified in this commit
 	Modified []string `json:"modified"`
 }
 
 // PayloadCommitVerification represents the GPG verification of a commit
 type PayloadCommitVerification struct {
+	// Whether the commit signature is verified
 	Verified bool `json:"verified"`
+	// The reason for the verification status
 	Reason string `json:"reason"`
+	// The GPG signature of the commit
 	Signature string `json:"signature"`
+	// The user who signed the commit
 	Signer *PayloadUser `json:"signer"`
+	// The signed payload content
 	Payload string `json:"payload"`
 }
 
@@ -119,10 +154,15 @@ var (
 
 // CreatePayload represents a payload information of create event.
 type CreatePayload struct {
+	// The SHA hash of the created reference
 	Sha string `json:"sha"`
+	// The full name of the created reference
 	Ref string `json:"ref"`
+	// The type of reference created (branch or tag)
 	RefType string `json:"ref_type"`
+	// The repository where the reference was created
 	Repo *Repository `json:"repository"`
+	// The user who created the reference
 	Sender *User `json:"sender"`
 }
 
@@ -161,10 +201,15 @@ const (
 
 // DeletePayload represents delete payload
 type DeletePayload struct {
+	// The name of the deleted reference
 	Ref string `json:"ref"`
+	// The type of reference deleted (branch or tag)
 	RefType string `json:"ref_type"`
+	// The type of entity that performed the deletion
 	PusherType PusherType `json:"pusher_type"`
+	// The repository where the reference was deleted
 	Repo *Repository `json:"repository"`
+	// The user who deleted the reference
 	Sender *User `json:"sender"`
 }
 
@@ -175,8 +220,11 @@ func (p *DeletePayload) JSONPayload() ([]byte, error) {
 
 // ForkPayload represents fork payload
 type ForkPayload struct {
+	// The forked repository (the new fork)
 	Forkee *Repository `json:"forkee"`
+	// The original repository that was forked
 	Repo *Repository `json:"repository"`
+	// The user who created the fork
 	Sender *User `json:"sender"`
 }
 
@@ -197,13 +245,21 @@ const (
 
 // IssueCommentPayload represents a payload information of issue comment event.
 type IssueCommentPayload struct {
+	// The action performed on the comment (created, edited, deleted)
 	Action HookIssueCommentAction `json:"action"`
+	// The issue that the comment belongs to
 	Issue *Issue `json:"issue"`
+	// The pull request if the comment is on a pull request
 	PullRequest *PullRequest `json:"pull_request,omitempty"`
+	// The comment that was acted upon
 	Comment *Comment `json:"comment"`
+	// Changes made to the comment (for edit actions)
 	Changes *ChangesPayload `json:"changes,omitempty"`
+	// The repository containing the issue/pull request
 	Repository *Repository `json:"repository"`
+	// The user who performed the action
 	Sender *User `json:"sender"`
+	// Whether this comment is on a pull request
 	IsPull bool `json:"is_pull"`
 }
 
@@ -224,9 +280,13 @@ const (
 
 // ReleasePayload represents a payload information of release event.
 type ReleasePayload struct {
+	// The action performed on the release (published, updated, deleted)
 	Action HookReleaseAction `json:"action"`
+	// The release that was acted upon
 	Release *Release `json:"release"`
+	// The repository containing the release
 	Repository *Repository `json:"repository"`
+	// The user who performed the action
 	Sender *User `json:"sender"`
 }
 
@@ -237,15 +297,25 @@ func (p *ReleasePayload) JSONPayload() ([]byte, error) {
 
 // PushPayload represents a payload information of push event.
 type PushPayload struct {
+	// The full name of the pushed reference
 	Ref string `json:"ref"`
+	// The SHA of the most recent commit before the push
 	Before string `json:"before"`
+	// The SHA of the most recent commit after the push
 	After string `json:"after"`
+	// URL to compare the changes in this push
 	CompareURL string `json:"compare_url"`
+	// List of commits included in the push
 	Commits []*PayloadCommit `json:"commits"`
+	// Total number of commits in the push
 	TotalCommits int `json:"total_commits"`
+	// The most recent commit in the push
 	HeadCommit *PayloadCommit `json:"head_commit"`
+	// The repository that was pushed to
 	Repo *Repository `json:"repository"`
+	// The user who performed the push
 	Pusher *User `json:"pusher"`
+	// The user who triggered the webhook
 	Sender *User `json:"sender"`
 }
 
@@ -313,12 +383,19 @@ const (
 
 // IssuePayload represents the payload information that is sent along with an issue event.
 type IssuePayload struct {
+	// The action performed on the issue
 	Action HookIssueAction `json:"action"`
+	// The index number of the issue
 	Index int64 `json:"number"`
+	// Changes made to the issue (for edit actions)
 	Changes *ChangesPayload `json:"changes,omitempty"`
+	// The issue that was acted upon
 	Issue *Issue `json:"issue"`
+	// The repository containing the issue
 	Repository *Repository `json:"repository"`
+	// The user who performed the action
 	Sender *User `json:"sender"`
+	// The commit ID related to the issue action
 	CommitID string `json:"commit_id"`
 }
 
@@ -329,26 +406,39 @@ func (p *IssuePayload) JSONPayload() ([]byte, error) {
 
 // ChangesFromPayload FIXME
 type ChangesFromPayload struct {
+	// The previous value before the change
 	From string `json:"from"`
 }
 
 // ChangesPayload represents the payload information of issue change
 type ChangesPayload struct {
+	// Changes made to the title
 	Title *ChangesFromPayload `json:"title,omitempty"`
+	// Changes made to the body/description
 	Body *ChangesFromPayload `json:"body,omitempty"`
+	// Changes made to the reference
 	Ref *ChangesFromPayload `json:"ref,omitempty"`
 }
 
 // PullRequestPayload represents a payload information of pull request event.
 type PullRequestPayload struct {
+	// The action performed on the pull request
 	Action HookIssueAction `json:"action"`
+	// The index number of the pull request
 	Index int64 `json:"number"`
+	// Changes made to the pull request (for edit actions)
 	Changes *ChangesPayload `json:"changes,omitempty"`
+	// The pull request that was acted upon
 	PullRequest *PullRequest `json:"pull_request"`
+	// The reviewer that was requested (for review request actions)
 	RequestedReviewer *User `json:"requested_reviewer"`
+	// The repository containing the pull request
 	Repository *Repository `json:"repository"`
+	// The user who performed the action
 	Sender *User `json:"sender"`
+	// The commit ID related to the pull request action
 	CommitID string `json:"commit_id"`
+	// The review information (for review actions)
 	Review *ReviewPayload `json:"review"`
 }
 
@@ -359,7 +449,9 @@ func (p *PullRequestPayload) JSONPayload() ([]byte, error) {
 
 // ReviewPayload FIXME
 type ReviewPayload struct {
+	// The type of review (approved, rejected, comment)
 	Type string `json:"type"`
+	// The content/body of the review
 	Content string `json:"content"`
 }
 
@@ -377,10 +469,15 @@ const (
 
 // WikiPayload payload for repository webhooks
 type WikiPayload struct {
+	// The action performed on the wiki page
 	Action HookWikiAction `json:"action"`
+	// The repository containing the wiki
 	Repository *Repository `json:"repository"`
+	// The user who performed the action
 	Sender *User `json:"sender"`
+	// The name of the wiki page
 	Page string `json:"page"`
+	// The comment/commit message for the wiki change
 	Comment string `json:"comment"`
 }
 
@@ -401,9 +498,13 @@ const (
 
 // RepositoryPayload payload for repository webhooks
 type RepositoryPayload struct {
+	// The action performed on the repository
 	Action HookRepoAction `json:"action"`
+	// The repository that was acted upon
 	Repository *Repository `json:"repository"`
+	// The organization that owns the repository (if applicable)
 	Organization *User `json:"organization"`
+	// The user who performed the action
 	Sender *User `json:"sender"`
 }
 
@@ -424,10 +525,15 @@ const (
 
 // PackagePayload represents a package payload
 type PackagePayload struct {
+	// The action performed on the package
 	Action HookPackageAction `json:"action"`
+	// The repository associated with the package
 	Repository *Repository `json:"repository"`
+	// The package that was acted upon
 	Package *Package `json:"package"`
+	// The organization that owns the package (if applicable)
 	Organization *Organization `json:"organization"`
+	// The user who performed the action
 	Sender *User `json:"sender"`
 }
 
@@ -438,10 +544,15 @@ func (p *PackagePayload) JSONPayload() ([]byte, error) {
 
 // WorkflowDispatchPayload represents a workflow dispatch payload
 type WorkflowDispatchPayload struct {
+	// The name or path of the workflow file
 	Workflow string `json:"workflow"`
+	// The git reference (branch, tag, or commit SHA) to run the workflow on
 	Ref string `json:"ref"`
+	// Input parameters for the workflow dispatch event
 	Inputs map[string]any `json:"inputs"`
+	// The repository containing the workflow
 	Repository *Repository `json:"repository"`
+	// The user who triggered the workflow dispatch
 	Sender *User `json:"sender"`
 }
 
@@ -453,18 +564,29 @@ func (p *WorkflowDispatchPayload) JSONPayload() ([]byte, error) {
 // CommitStatusPayload represents a payload information of commit status event.
 type CommitStatusPayload struct {
 	// TODO: add Branches per https://docs.github.com/en/webhooks/webhook-events-and-payloads#status
+	// The commit that the status is associated with
 	Commit *PayloadCommit `json:"commit"`
+	// The context/identifier for this status check
 	Context string `json:"context"`
 	// swagger:strfmt date-time
+	// The date and time when the status was created
 	CreatedAt time.Time `json:"created_at"`
+	// A short description of the status
 	Description string `json:"description"`
+	// The unique identifier of the status
 	ID int64 `json:"id"`
+	// The repository containing the commit
 	Repo *Repository `json:"repository"`
+	// The user who created the status
 	Sender *User `json:"sender"`
+	// The SHA hash of the commit
 	SHA string `json:"sha"`
+	// The state of the status (pending, success, error, failure)
 	State string `json:"state"`
+	// The target URL to associate with this status
 	TargetURL string `json:"target_url"`
 	// swagger:strfmt date-time
+	// The date and time when the status was last updated
 	UpdatedAt *time.Time `json:"updated_at"`
 }
 
@@ -475,12 +597,19 @@ func (p *CommitStatusPayload) JSONPayload() ([]byte, error) {
 
 // WorkflowRunPayload represents a payload information of workflow run event.
 type WorkflowRunPayload struct {
+	// The action performed on the workflow run
 	Action string `json:"action"`
+	// The workflow definition
 	Workflow *ActionWorkflow `json:"workflow"`
+	// The workflow run that was acted upon
 	WorkflowRun *ActionWorkflowRun `json:"workflow_run"`
+	// The pull request associated with the workflow run (if applicable)
 	PullRequest *PullRequest `json:"pull_request,omitempty"`
+	// The organization that owns the repository (if applicable)
 	Organization *Organization `json:"organization,omitempty"`
+	// The repository containing the workflow
 	Repo *Repository `json:"repository"`
+	// The user who triggered the workflow run
 	Sender *User `json:"sender"`
 }
 
@@ -491,11 +620,17 @@ func (p *WorkflowRunPayload) JSONPayload() ([]byte, error) {
 
 // WorkflowJobPayload represents a payload information of workflow job event.
 type WorkflowJobPayload struct {
+	// The action performed on the workflow job
 	Action string `json:"action"`
+	// The workflow job that was acted upon
 	WorkflowJob *ActionWorkflowJob `json:"workflow_job"`
+	// The pull request associated with the workflow job (if applicable)
 	PullRequest *PullRequest `json:"pull_request,omitempty"`
+	// The organization that owns the repository (if applicable)
 	Organization *Organization `json:"organization,omitempty"`
+	// The repository containing the workflow
 	Repo *Repository `json:"repository"`
+	// The user who triggered the workflow job
 	Sender *User `json:"sender"`
 }
 

modules/structs/issue_comment.go

@@ -9,14 +9,23 @@ import (
 
 // Comment represents a comment on a commit or issue
 type Comment struct {
+	// ID is the unique identifier for the comment
 	ID int64 `json:"id"`
+	// HTMLURL is the web URL for viewing the comment
 	HTMLURL string `json:"html_url"`
+	// PRURL is the API URL for the pull request (if applicable)
 	PRURL string `json:"pull_request_url"`
+	// IssueURL is the API URL for the issue
 	IssueURL string `json:"issue_url"`
+	// Poster is the user who posted the comment
 	Poster *User `json:"user"`
+	// OriginalAuthor is the original author name (for imported comments)
 	OriginalAuthor string `json:"original_author"`
+	// OriginalAuthorID is the original author ID (for imported comments)
 	OriginalAuthorID int64 `json:"original_author_id"`
+	// Body contains the comment text content
 	Body string `json:"body"`
+	// Attachments contains files attached to the comment
 	Attachments []*Attachment `json:"assets"`
 	// swagger:strfmt date-time
 	Created time.Time `json:"created_at"`
@@ -27,24 +36,33 @@ type Comment struct {
 // CreateIssueCommentOption options for creating a comment on an issue
 type CreateIssueCommentOption struct {
 	// required:true
+	// Body is the comment text content
 	Body string `json:"body" binding:"Required"`
 }
 
 // EditIssueCommentOption options for editing a comment
 type EditIssueCommentOption struct {
 	// required: true
+	// Body is the updated comment text content
 	Body string `json:"body" binding:"Required"`
 }
 
 // TimelineComment represents a timeline comment (comment of any type) on a commit or issue
 type TimelineComment struct {
+	// ID is the unique identifier for the timeline comment
 	ID int64 `json:"id"`
+	// Type indicates the type of timeline event
 	Type string `json:"type"`
 
+	// HTMLURL is the web URL for viewing the comment
 	HTMLURL string `json:"html_url"`
+	// PRURL is the API URL for the pull request (if applicable)
 	PRURL string `json:"pull_request_url"`
+	// IssueURL is the API URL for the issue
 	IssueURL string `json:"issue_url"`
+	// Poster is the user who created the timeline event
 	Poster *User `json:"user"`
+	// Body contains the timeline event content
 	Body string `json:"body"`
 	// swagger:strfmt date-time
 	Created time.Time `json:"created_at"`

modules/structs/issue_label.go

@@ -7,7 +7,9 @@ package structs
 // Label a label to an issue or a pr
 // swagger:model
 type Label struct {
+	// ID is the unique identifier for the label
 	ID int64 `json:"id"`
+	// Name is the display name of the label
 	Name string `json:"name"`
 	// example: false
 	Exclusive bool `json:"exclusive"`
@@ -15,19 +17,23 @@ type Label struct {
 	IsArchived bool `json:"is_archived"`
 	// example: 00aabb
 	Color string `json:"color"`
+	// Description provides additional context about the label's purpose
 	Description string `json:"description"`
+	// URL is the API endpoint for accessing this label
 	URL string `json:"url"`
 }
 
 // CreateLabelOption options for creating a label
 type CreateLabelOption struct {
 	// required:true
+	// Name is the display name for the new label
 	Name string `json:"name" binding:"Required"`
 	// example: false
 	Exclusive bool `json:"exclusive"`
 	// required:true
 	// example: #00aabb
 	Color string `json:"color" binding:"Required"`
+	// Description provides additional context about the label's purpose
 	Description string `json:"description"`
 	// example: false
 	IsArchived bool `json:"is_archived"`
@@ -35,11 +41,13 @@ type CreateLabelOption struct {
 
 // EditLabelOption options for editing a label
 type EditLabelOption struct {
+	// Name is the new display name for the label
 	Name *string `json:"name"`
 	// example: false
 	Exclusive *bool `json:"exclusive"`
 	// example: #00aabb
 	Color *string `json:"color"`
+	// Description provides additional context about the label's purpose
 	Description *string `json:"description"`
 	// example: false
 	IsArchived *bool `json:"is_archived"`
@@ -54,10 +62,12 @@ type IssueLabelsOption struct {
 
 // LabelTemplate info of a Label template
 type LabelTemplate struct {
+	// Name is the display name of the label template
 	Name string `json:"name"`
 	// example: false
 	Exclusive bool `json:"exclusive"`
 	// example: 00aabb
 	Color string `json:"color"`
+	// Description provides additional context about the label template's purpose
 	Description string `json:"description"`
 }

modules/structs/issue_milestone.go

@@ -9,11 +9,17 @@ import (
 
 // Milestone milestone is a collection of issues on one repository
 type Milestone struct {
+	// ID is the unique identifier for the milestone
 	ID int64 `json:"id"`
+	// Title is the title of the milestone
 	Title string `json:"title"`
+	// Description provides details about the milestone
 	Description string `json:"description"`
+	// State indicates if the milestone is open or closed
 	State StateType `json:"state"`
+	// OpenIssues is the number of open issues in this milestone
 	OpenIssues int `json:"open_issues"`
+	// ClosedIssues is the number of closed issues in this milestone
 	ClosedIssues int `json:"closed_issues"`
 	// swagger:strfmt date-time
 	Created time.Time `json:"created_at"`
@@ -27,18 +33,26 @@ type Milestone struct {
 
 // CreateMilestoneOption options for creating a milestone
 type CreateMilestoneOption struct {
+	// Title is the title of the new milestone
 	Title string `json:"title"`
+	// Description provides details about the milestone
 	Description string `json:"description"`
 	// swagger:strfmt date-time
+	// Deadline is the due date for the milestone
 	Deadline *time.Time `json:"due_on"`
 	// enum: open,closed
+	// State indicates the initial state of the milestone
 	State string `json:"state"`
 }
 
 // EditMilestoneOption options for editing a milestone
 type EditMilestoneOption struct {
+	// Title is the updated title of the milestone
 	Title string `json:"title"`
+	// Description provides updated details about the milestone
 	Description *string `json:"description"`
+	// State indicates the updated state of the milestone
 	State *string `json:"state"`
+	// Deadline is the updated due date for the milestone
 	Deadline *time.Time `json:"due_on"`
 }

modules/structs/issue_reaction.go

@@ -9,13 +9,17 @@ import (
 
 // EditReactionOption contain the reaction type
 type EditReactionOption struct {
+	// The reaction content (e.g., emoji or reaction type)
 	Reaction string `json:"content"`
 }
 
 // Reaction contain one reaction
 type Reaction struct {
+	// The user who created the reaction
 	User *User `json:"user"`
+	// The reaction content (e.g., emoji or reaction type)
 	Reaction string `json:"content"`
 	// swagger:strfmt date-time
+	// The date and time when the reaction was created
 	Created time.Time `json:"created_at"`
 }

modules/structs/issue_stopwatch.go

@@ -10,12 +10,19 @@ import (
 // StopWatch represent a running stopwatch
 type StopWatch struct {
 	// swagger:strfmt date-time
+	// Created is the time when the stopwatch was started
 	Created time.Time `json:"created"`
+	// Seconds is the total elapsed time in seconds
 	Seconds int64 `json:"seconds"`
+	// Duration is a human-readable duration string
 	Duration string `json:"duration"`
+	// IssueIndex is the index number of the associated issue
 	IssueIndex int64 `json:"issue_index"`
+	// IssueTitle is the title of the associated issue
 	IssueTitle string `json:"issue_title"`
+	// RepoOwnerName is the name of the repository owner
 	RepoOwnerName string `json:"repo_owner_name"`
+	// RepoName is the name of the repository
 	RepoName string `json:"repo_name"`
 }
 

modules/structs/issue_tracked_time.go

@@ -20,6 +20,7 @@ type AddTimeOption struct {
 
 // TrackedTime worked time for an issue / pr
 type TrackedTime struct {
+	// ID is the unique identifier for the tracked time entry
 	ID int64 `json:"id"`
 	// swagger:strfmt date-time
 	Created time.Time `json:"created"`
@@ -31,6 +32,7 @@ type TrackedTime struct {
 	UserName string `json:"user_name"`
 	// deprecated (only for backwards compatibility)
 	IssueID int64 `json:"issue_id"`
+	// Issue contains the associated issue information
 	Issue *Issue `json:"issue"`
 }
 

modules/structs/lfs_lock.go

@@ -10,55 +10,72 @@ import (
 // LFSLock represent a lock
 // for use with the locks API.
 type LFSLock struct {
+	// The unique identifier of the lock
 	ID string `json:"id"`
+	// The file path that is locked
 	Path string `json:"path"`
+	// The timestamp when the lock was created
 	LockedAt time.Time `json:"locked_at"`
+	// The owner of the lock
 	Owner *LFSLockOwner `json:"owner"`
 }
 
 // LFSLockOwner represent a lock owner
 // for use with the locks API.
 type LFSLockOwner struct {
+	// The name of the lock owner
 	Name string `json:"name"`
 }
 
 // LFSLockRequest contains the path of the lock to create
 // https://github.com/git-lfs/git-lfs/blob/master/docs/api/locking.md#create-lock
 type LFSLockRequest struct {
+	// The file path to lock
 	Path string `json:"path"`
 }
 
 // LFSLockResponse represent a lock created
 // https://github.com/git-lfs/git-lfs/blob/master/docs/api/locking.md#create-lock
 type LFSLockResponse struct {
+	// The created lock
 	Lock *LFSLock `json:"lock"`
 }
 
 // LFSLockList represent a list of lock requested
 // https://github.com/git-lfs/git-lfs/blob/master/docs/api/locking.md#list-locks
 type LFSLockList struct {
+	// The list of locks
 	Locks []*LFSLock `json:"locks"`
+	// The cursor for pagination to the next set of results
 	Next string `json:"next_cursor,omitempty"`
 }
 
 // LFSLockListVerify represent a list of lock verification requested
 // https://github.com/git-lfs/git-lfs/blob/master/docs/api/locking.md#list-locks-for-verification
 type LFSLockListVerify struct {
+	// Locks owned by the requesting user
 	Ours []*LFSLock `json:"ours"`
+	// Locks owned by other users
 	Theirs []*LFSLock `json:"theirs"`
+	// The cursor for pagination to the next set of results
 	Next string `json:"next_cursor,omitempty"`
 }
 
 // LFSLockError contains information on the error that occurs
 type LFSLockError struct {
+	// The error message
 	Message string `json:"message"`
+	// The lock related to the error, if any
 	Lock *LFSLock `json:"lock,omitempty"`
+	// URL to documentation about the error
 	Documentation string `json:"documentation_url,omitempty"`
+	// The request ID for debugging purposes
 	RequestID string `json:"request_id,omitempty"`
 }
 
 // LFSLockDeleteRequest contains params of a delete request
 // https://github.com/git-lfs/git-lfs/blob/master/docs/api/locking.md#delete-lock
 type LFSLockDeleteRequest struct {
+	// Whether to force delete the lock even if not owned by the requester
 	Force bool `json:"force"`
 }

modules/structs/mirror.go

@@ -7,24 +7,35 @@ import "time"
 
 // CreatePushMirrorOption represents need information to create a push mirror of a repository.
 type CreatePushMirrorOption struct {
+	// The remote repository URL to push to
 	RemoteAddress string `json:"remote_address"`
+	// The username for authentication with the remote repository
 	RemoteUsername string `json:"remote_username"`
+	// The password for authentication with the remote repository
 	RemotePassword string `json:"remote_password"`
+	// The sync interval for automatic updates
 	Interval string `json:"interval"`
+	// Whether to sync on every commit
 	SyncOnCommit bool `json:"sync_on_commit"`
 }
 
 // PushMirror represents information of a push mirror
 // swagger:model
 type PushMirror struct {
+	// The name of the source repository
 	RepoName string `json:"repo_name"`
+	// The name of the remote in the git configuration
 	RemoteName string `json:"remote_name"`
+	// The remote repository URL being mirrored to
 	RemoteAddress string `json:"remote_address"`
 	// swagger:strfmt date-time
 	CreatedUnix time.Time `json:"created"`
 	// swagger:strfmt date-time
 	LastUpdateUnix *time.Time `json:"last_update"`
+	// The last error message encountered during sync
 	LastError string `json:"last_error"`
+	// The sync interval for automatic updates
 	Interval string `json:"interval"`
+	// Whether to sync on every commit
 	SyncOnCommit bool `json:"sync_on_commit"`
 }

modules/structs/miscellaneous.go

@@ -5,13 +5,17 @@ package structs
 
 // SearchResults results of a successful search
 type SearchResults struct {
+	// OK indicates if the search was successful
 	OK bool `json:"ok"`
+	// Data contains the repository search results
 	Data []*Repository `json:"data"`
 }
 
 // SearchError error of a failed search
 type SearchError struct {
+	// OK indicates the search status (always false for errors)
 	OK bool `json:"ok"`
+	// Error contains the error message
 	Error string `json:"error"`
 }
 
@@ -73,33 +77,46 @@ type MarkdownRender string
 
 // ServerVersion wraps the version of the server
 type ServerVersion struct {
+	// Version is the server version string
 	Version string `json:"version"`
 }
 
 // GitignoreTemplateInfo name and text of a gitignore template
 type GitignoreTemplateInfo struct {
+	// Name is the name of the gitignore template
 	Name string `json:"name"`
+	// Source contains the content of the gitignore template
 	Source string `json:"source"`
 }
 
 // LicensesListEntry is used for the API
 type LicensesTemplateListEntry struct {
+	// Key is the unique identifier for the license template
 	Key string `json:"key"`
+	// Name is the display name of the license
 	Name string `json:"name"`
+	// URL is the reference URL for the license
 	URL string `json:"url"`
 }
 
 // LicensesInfo contains information about a License
 type LicenseTemplateInfo struct {
+	// Key is the unique identifier for the license template
 	Key string `json:"key"`
+	// Name is the display name of the license
 	Name string `json:"name"`
+	// URL is the reference URL for the license
 	URL string `json:"url"`
+	// Implementation contains license implementation details
 	Implementation string `json:"implementation"`
+	// Body contains the full text of the license
 	Body string `json:"body"`
 }
 
 // APIError is an api error with a message
 type APIError struct {
+	// Message contains the error description
 	Message string `json:"message"`
+	// URL contains the documentation URL for this error
 	URL string `json:"url"`
 }

modules/structs/nodeinfo.go

@@ -5,39 +5,58 @@ package structs
 
 // NodeInfo contains standardized way of exposing metadata about a server running one of the distributed social networks
 type NodeInfo struct {
+	// Version specifies the schema version
 	Version string `json:"version"`
+	// Software contains information about the server software
 	Software NodeInfoSoftware `json:"software"`
+	// Protocols lists the protocols supported by this server
 	Protocols []string `json:"protocols"`
+	// Services contains third party services this server can connect to
 	Services NodeInfoServices `json:"services"`
+	// OpenRegistrations indicates if new user registrations are accepted
 	OpenRegistrations bool `json:"openRegistrations"`
+	// Usage contains server usage statistics
 	Usage NodeInfoUsage `json:"usage"`
+	// Metadata contains free form key value pairs for software specific values
 	Metadata struct{} `json:"metadata"`
 }
 
 // NodeInfoSoftware contains Metadata about server software in use
 type NodeInfoSoftware struct {
+	// Name is the canonical name of this server software
 	Name string `json:"name"`
+	// Version is the version of this server software
 	Version string `json:"version"`
+	// Repository is the URL to the source code repository
 	Repository string `json:"repository"`
+	// Homepage is the URL to the homepage of this server software
 	Homepage string `json:"homepage"`
 }
 
 // NodeInfoServices contains the third party sites this server can connect to via their application API
 type NodeInfoServices struct {
+	// Inbound lists services that can deliver content to this server
 	Inbound []string `json:"inbound"`
+	// Outbound lists services this server can deliver content to
 	Outbound []string `json:"outbound"`
 }
 
 // NodeInfoUsage contains usage statistics for this server
 type NodeInfoUsage struct {
+	// Users contains user statistics
 	Users NodeInfoUsageUsers `json:"users"`
+	// LocalPosts is the total amount of posts made by users local to this server
 	LocalPosts int `json:"localPosts,omitempty"`
+	// LocalComments is the total amount of comments made by users local to this server
 	LocalComments int `json:"localComments,omitempty"`
 }
 
 // NodeInfoUsageUsers contains statistics about the users of this server
 type NodeInfoUsageUsers struct {
+	// Total is the total amount of users on this server
 	Total int `json:"total,omitempty"`
+	// ActiveHalfyear is the amount of users that signed in at least once in the last 180 days
 	ActiveHalfyear int `json:"activeHalfyear,omitempty"`
+	// ActiveMonth is the amount of users that signed in at least once in the last 30 days
 	ActiveMonth int `json:"activeMonth,omitempty"`
 }

modules/structs/notifications.go

@@ -9,28 +9,43 @@ import (
 
 // NotificationThread expose Notification on API
 type NotificationThread struct {
+	// ID is the unique identifier for the notification thread
 	ID int64 `json:"id"`
+	// Repository is the repository associated with the notification
 	Repository *Repository `json:"repository"`
+	// Subject contains details about the notification subject
 	Subject *NotificationSubject `json:"subject"`
+	// Unread indicates if the notification has been read
 	Unread bool `json:"unread"`
+	// Pinned indicates if the notification is pinned
 	Pinned bool `json:"pinned"`
+	// UpdatedAt is the time when the notification was last updated
 	UpdatedAt time.Time `json:"updated_at"`
+	// URL is the API URL for this notification thread
 	URL string `json:"url"`
 }
 
 // NotificationSubject contains the notification subject (Issue/Pull/Commit)
 type NotificationSubject struct {
+	// Title is the title of the notification subject
 	Title string `json:"title"`
+	// URL is the API URL for the notification subject
 	URL string `json:"url"`
+	// LatestCommentURL is the API URL for the latest comment
 	LatestCommentURL string `json:"latest_comment_url"`
+	// HTMLURL is the web URL for the notification subject
 	HTMLURL string `json:"html_url"`
+	// LatestCommentHTMLURL is the web URL for the latest comment
 	LatestCommentHTMLURL string `json:"latest_comment_html_url"`
+	// Type indicates the type of the notification subject
 	Type NotifySubjectType `json:"type" binding:"In(Issue,Pull,Commit,Repository)"`
+	// State indicates the current state of the notification subject
 	State StateType `json:"state"`
 }
 
 // NotificationCount number of unread notifications
 type NotificationCount struct {
+	// New is the number of unread notifications
 	New int64 `json:"new"`
 }
 

modules/structs/org.go

@@ -5,15 +5,25 @@ package structs
 
 // Organization represents an organization
 type Organization struct {
+	// The unique identifier of the organization
 	ID int64 `json:"id"`
+	// The name of the organization
 	Name string `json:"name"`
+	// The full display name of the organization
 	FullName string `json:"full_name"`
+	// The email address of the organization
 	Email string `json:"email"`
+	// The URL of the organization's avatar
 	AvatarURL string `json:"avatar_url"`
+	// The description of the organization
 	Description string `json:"description"`
+	// The website URL of the organization
 	Website string `json:"website"`
+	// The location of the organization
 	Location string `json:"location"`
+	// The visibility level of the organization (public, limited, private)
 	Visibility string `json:"visibility"`
+	// Whether repository administrators can change team access
 	RepoAdminChangeTeamAccess bool `json:"repo_admin_change_team_access"`
 	// username of the organization
 	// deprecated
@@ -22,10 +32,15 @@ type Organization struct {
 
 // OrganizationPermissions list different users permissions on an organization
 type OrganizationPermissions struct {
+	// Whether the user is an owner of the organization
 	IsOwner bool `json:"is_owner"`
+	// Whether the user is an admin of the organization
 	IsAdmin bool `json:"is_admin"`
+	// Whether the user can write to the organization
 	CanWrite bool `json:"can_write"`
+	// Whether the user can read the organization
 	CanRead bool `json:"can_read"`
+	// Whether the user can create repositories in the organization
 	CanCreateRepository bool `json:"can_create_repository"`
 }
 
@@ -34,14 +49,20 @@ type CreateOrgOption struct {
 	// username of the organization
 	// required: true
 	UserName string `json:"username" binding:"Required;Username;MaxSize(40)"`
+	// The full display name of the organization
 	FullName string `json:"full_name" binding:"MaxSize(100)"`
+	// The email address of the organization
 	Email string `json:"email" binding:"MaxSize(255)"`
+	// The description of the organization
 	Description string `json:"description" binding:"MaxSize(255)"`
+	// The website URL of the organization
 	Website string `json:"website" binding:"ValidUrl;MaxSize(255)"`
+	// The location of the organization
 	Location string `json:"location" binding:"MaxSize(50)"`
 	// possible values are `public` (default), `limited` or `private`
 	// enum: public,limited,private
 	Visibility string `json:"visibility" binding:"In(,public,limited,private)"`
+	// Whether repository administrators can change team access
 	RepoAdminChangeTeamAccess bool `json:"repo_admin_change_team_access"`
 }
 
@@ -49,14 +70,20 @@ type CreateOrgOption struct {
 
 // EditOrgOption options for editing an organization
 type EditOrgOption struct {
+	// The full display name of the organization
 	FullName string `json:"full_name" binding:"MaxSize(100)"`
+	// The email address of the organization
 	Email string `json:"email" binding:"MaxSize(255)"`
+	// The description of the organization
 	Description string `json:"description" binding:"MaxSize(255)"`
+	// The website URL of the organization
 	Website string `json:"website" binding:"ValidUrl;MaxSize(255)"`
+	// The location of the organization
 	Location string `json:"location" binding:"MaxSize(50)"`
 	// possible values are `public`, `limited` or `private`
 	// enum: public,limited,private
 	Visibility string `json:"visibility" binding:"In(,public,limited,private)"`
+	// Whether repository administrators can change team access
 	RepoAdminChangeTeamAccess *bool `json:"repo_admin_change_team_access"`
 }
 

modules/structs/org_member.go

@@ -5,5 +5,6 @@ package structs
 
 // AddOrgMembershipOption add user to organization options
 type AddOrgMembershipOption struct {
+	// Role is the role to assign to the organization member
 	Role string `json:"role" binding:"Required"`
 }

modules/structs/org_team.go

@@ -6,10 +6,15 @@ package structs
 
 // Team represents a team in an organization
 type Team struct {
+	// The unique identifier of the team
 	ID int64 `json:"id"`
+	// The name of the team
 	Name string `json:"name"`
+	// The description of the team
 	Description string `json:"description"`
+	// The organization that the team belongs to
 	Organization *Organization `json:"organization"`
+	// Whether the team has access to all repositories in the organization
 	IncludesAllRepositories bool `json:"includes_all_repositories"`
 	// enum: none,read,write,admin,owner
 	Permission string `json:"permission"`
@@ -18,6 +23,7 @@ type Team struct {
 	Units []string `json:"units"`
 	// example: {"repo.code":"read","repo.issues":"write","repo.ext_issues":"none","repo.wiki":"admin","repo.pulls":"owner","repo.releases":"none","repo.projects":"none","repo.ext_wiki":"none"}
 	UnitsMap map[string]string `json:"units_map"`
+	// Whether the team can create repositories in the organization
 	CanCreateOrgRepo bool `json:"can_create_org_repo"`
 }
 
@@ -25,7 +31,9 @@ type Team struct {
 type CreateTeamOption struct {
 	// required: true
 	Name string `json:"name" binding:"Required;AlphaDashDot;MaxSize(255)"`
+	// The description of the team
 	Description string `json:"description" binding:"MaxSize(255)"`
+	// Whether the team has access to all repositories in the organization
 	IncludesAllRepositories bool `json:"includes_all_repositories"`
 	// enum: read,write,admin
 	Permission string `json:"permission"`
@@ -34,6 +42,7 @@ type CreateTeamOption struct {
 	Units []string `json:"units"`
 	// example: {"repo.actions","repo.packages","repo.code":"read","repo.issues":"write","repo.ext_issues":"none","repo.wiki":"admin","repo.pulls":"owner","repo.releases":"none","repo.projects":"none","repo.ext_wiki":"none"}
 	UnitsMap map[string]string `json:"units_map"`
+	// Whether the team can create repositories in the organization
 	CanCreateOrgRepo bool `json:"can_create_org_repo"`
 }
 
@@ -41,7 +50,9 @@ type CreateTeamOption struct {
 type EditTeamOption struct {
 	// required: true
 	Name string `json:"name" binding:"AlphaDashDot;MaxSize(255)"`
+	// The description of the team
 	Description *string `json:"description" binding:"MaxSize(255)"`
+	// Whether the team has access to all repositories in the organization
 	IncludesAllRepositories *bool `json:"includes_all_repositories"`
 	// enum: read,write,admin
 	Permission string `json:"permission"`
@@ -50,5 +61,6 @@ type EditTeamOption struct {
 	Units []string `json:"units"`
 	// example: {"repo.code":"read","repo.issues":"write","repo.ext_issues":"none","repo.wiki":"admin","repo.pulls":"owner","repo.releases":"none","repo.projects":"none","repo.ext_wiki":"none"}
 	UnitsMap map[string]string `json:"units_map"`
+	// Whether the team can create repositories in the organization
 	CanCreateOrgRepo *bool `json:"can_create_org_repo"`
 }

modules/structs/package.go

@@ -9,25 +9,41 @@ import (
 
 // Package represents a package
 type Package struct {
+	// The unique identifier of the package
 	ID int64 `json:"id"`
+	// The owner of the package
 	Owner *User `json:"owner"`
+	// The repository that contains this package
 	Repository *Repository `json:"repository"`
+	// The user who created this package
 	Creator *User `json:"creator"`
+	// The type of the package (e.g., npm, maven, docker)
 	Type string `json:"type"`
+	// The name of the package
 	Name string `json:"name"`
+	// The version of the package
 	Version string `json:"version"`
+	// The HTML URL to view the package
 	HTMLURL string `json:"html_url"`
 	// swagger:strfmt date-time
+	// The date and time when the package was created
 	CreatedAt time.Time `json:"created_at"`
 }
 
 // PackageFile represents a package file
 type PackageFile struct {
+	// The unique identifier of the package file
 	ID int64 `json:"id"`
+	// The size of the package file in bytes
 	Size int64 `json:"size"`
+	// The name of the package file
 	Name string `json:"name"`
+	// The MD5 hash of the package file
 	HashMD5 string `json:"md5"`
+	// The SHA1 hash of the package file
 	HashSHA1 string `json:"sha1"`
+	// The SHA256 hash of the package file
 	HashSHA256 string `json:"sha256"`
+	// The SHA512 hash of the package file
 	HashSHA512 string `json:"sha512"`
 }

modules/structs/pull.go

@@ -9,44 +9,74 @@ import (
 
 // PullRequest represents a pull request
 type PullRequest struct {
+	// The unique identifier of the pull request
 	ID int64 `json:"id"`
+	// The API URL of the pull request
 	URL string `json:"url"`
+	// The pull request number
 	Index int64 `json:"number"`
+	// The user who created the pull request
 	Poster *User `json:"user"`
+	// The title of the pull request
 	Title string `json:"title"`
+	// The description body of the pull request
 	Body string `json:"body"`
+	// The labels attached to the pull request
 	Labels []*Label `json:"labels"`
+	// The milestone associated with the pull request
 	Milestone *Milestone `json:"milestone"`
+	// The primary assignee of the pull request
 	Assignee *User `json:"assignee"`
+	// The list of users assigned to the pull request
 	Assignees []*User `json:"assignees"`
+	// The users requested to review the pull request
 	RequestedReviewers []*User `json:"requested_reviewers"`
+	// The teams requested to review the pull request
 	RequestedReviewersTeams []*Team `json:"requested_reviewers_teams"`
+	// The current state of the pull request
 	State StateType `json:"state"`
+	// Whether the pull request is a draft
 	Draft bool `json:"draft"`
+	// Whether the pull request conversation is locked
 	IsLocked bool `json:"is_locked"`
+	// The number of comments on the pull request
 	Comments int `json:"comments"`
 
 	// number of review comments made on the diff of a PR review (not including comments on commits or issues in a PR)
 	ReviewComments int `json:"review_comments,omitempty"`
 
+	// The number of lines added in the pull request
 	Additions *int `json:"additions,omitempty"`
+	// The number of lines deleted in the pull request
 	Deletions *int `json:"deletions,omitempty"`
+	// The number of files changed in the pull request
 	ChangedFiles *int `json:"changed_files,omitempty"`
 
+	// The HTML URL to view the pull request
 	HTMLURL string `json:"html_url"`
+	// The URL to download the diff patch
 	DiffURL string `json:"diff_url"`
+	// The URL to download the patch file
 	PatchURL string `json:"patch_url"`
 
+	// Whether the pull request can be merged
 	Mergeable bool `json:"mergeable"`
+	// Whether the pull request has been merged
 	HasMerged bool `json:"merged"`
 	// swagger:strfmt date-time
 	Merged *time.Time `json:"merged_at"`
+	// The SHA of the merge commit
 	MergedCommitID *string `json:"merge_commit_sha"`
+	// The user who merged the pull request
 	MergedBy *User `json:"merged_by"`
+	// Whether maintainers can edit the pull request
 	AllowMaintainerEdit bool `json:"allow_maintainer_edit"`
 
+	// Information about the base branch
 	Base *PRBranchInfo `json:"base"`
+	// Information about the head branch
 	Head *PRBranchInfo `json:"head"`
+	// The merge base commit SHA
 	MergeBase string `json:"merge_base"`
 
 	// swagger:strfmt date-time
@@ -59,65 +89,103 @@ type PullRequest struct {
 	// swagger:strfmt date-time
 	Closed *time.Time `json:"closed_at"`
 
+	// The pin order for the pull request
 	PinOrder int `json:"pin_order"`
 }
 
 // PRBranchInfo information about a branch
 type PRBranchInfo struct {
+	// The display name of the branch
 	Name string `json:"label"`
+	// The git reference of the branch
 	Ref string `json:"ref"`
+	// The commit SHA of the branch head
 	Sha string `json:"sha"`
+	// The unique identifier of the repository
 	RepoID int64 `json:"repo_id"`
+	// The repository information
 	Repository *Repository `json:"repo"`
 }
 
 // ListPullRequestsOptions options for listing pull requests
 type ListPullRequestsOptions struct {
+	// The page number for pagination
 	Page int `json:"page"`
+	// The state filter for pull requests
 	State string `json:"state"`
 }
 
 // CreatePullRequestOption options when creating a pull request
 type CreatePullRequestOption struct {
+	// The head branch for the pull request, it could be a branch name on the base repository or
+	// a form like `<username>:<branch>` which refers to the user's fork repository's branch.
 	Head string `json:"head" binding:"Required"`
+	// The base branch for the pull request
 	Base string `json:"base" binding:"Required"`
+	// The title of the pull request
 	Title string `json:"title" binding:"Required"`
+	// The description body of the pull request
 	Body string `json:"body"`
+	// The primary assignee username
 	Assignee string `json:"assignee"`
+	// The list of assignee usernames
 	Assignees []string `json:"assignees"`
+	// The milestone ID to assign to the pull request
 	Milestone int64 `json:"milestone"`
+	// The list of label IDs to assign to the pull request
 	Labels []int64 `json:"labels"`
 	// swagger:strfmt date-time
 	Deadline *time.Time `json:"due_date"`
+	// The list of reviewer usernames
 	Reviewers []string `json:"reviewers"`
+	// The list of team reviewer names
 	TeamReviewers []string `json:"team_reviewers"`
 }
 
 // EditPullRequestOption options when modify pull request
 type EditPullRequestOption struct {
+	// The new title for the pull request
 	Title string `json:"title"`
+	// The new description body for the pull request
 	Body *string `json:"body"`
+	// The new base branch for the pull request
 	Base string `json:"base"`
+	// The new primary assignee username
 	Assignee string `json:"assignee"`
+	// The new list of assignee usernames
 	Assignees []string `json:"assignees"`
+	// The new milestone ID for the pull request
 	Milestone int64 `json:"milestone"`
+	// The new list of label IDs for the pull request
 	Labels []int64 `json:"labels"`
+	// The new state for the pull request
 	State *string `json:"state"`
 	// swagger:strfmt date-time
 	Deadline *time.Time `json:"due_date"`
+	// Whether to remove the current deadline
 	RemoveDeadline *bool `json:"unset_due_date"`
+	// Whether to allow maintainer edits
 	AllowMaintainerEdit *bool `json:"allow_maintainer_edit"`
 }
 
 // ChangedFile store information about files affected by the pull request
 type ChangedFile struct {
+	// The name of the changed file
 	Filename string `json:"filename"`
+	// The previous filename if the file was renamed
 	PreviousFilename string `json:"previous_filename,omitempty"`
+	// The status of the file change (added, modified, deleted, etc.)
 	Status string `json:"status"`
+	// The number of lines added to the file
 	Additions int `json:"additions"`
+	// The number of lines deleted from the file
 	Deletions int `json:"deletions"`
+	// The total number of changes to the file
 	Changes int `json:"changes"`
+	// The HTML URL to view the file changes
 	HTMLURL string `json:"html_url,omitempty"`
+	// The API URL to get the file contents
 	ContentsURL string `json:"contents_url,omitempty"`
+	// The raw URL to download the file
 	RawURL string `json:"raw_url,omitempty"`
 }

modules/structs/pull_review.go

@@ -42,7 +42,9 @@ type PullReview struct {
 	// swagger:strfmt date-time
 	Updated time.Time `json:"updated_at"`
 
+	// HTMLURL is the web URL for viewing the review
 	HTMLURL string `json:"html_url"`
+	// HTMLPullURL is the web URL for the pull request
 	HTMLPullURL string `json:"pull_request_url"`
 }
 

modules/structs/release.go

@@ -9,23 +9,37 @@ import (
 
 // Release represents a repository release
 type Release struct {
+	// The unique identifier of the release
 	ID int64 `json:"id"`
+	// The name of the git tag associated with the release
 	TagName string `json:"tag_name"`
+	// The target commitish for the release
 	Target string `json:"target_commitish"`
+	// The display title of the release
 	Title string `json:"name"`
+	// The release notes or description
 	Note string `json:"body"`
+	// The API URL of the release
 	URL string `json:"url"`
+	// The HTML URL to view the release
 	HTMLURL string `json:"html_url"`
+	// The URL to download the tarball archive
 	TarURL string `json:"tarball_url"`
+	// The URL to download the zip archive
 	ZipURL string `json:"zipball_url"`
+	// The URL template for uploading release assets
 	UploadURL string `json:"upload_url"`
+	// Whether the release is a draft
 	IsDraft bool `json:"draft"`
+	// Whether the release is a prerelease
 	IsPrerelease bool `json:"prerelease"`
 	// swagger:strfmt date-time
 	CreatedAt time.Time `json:"created_at"`
 	// swagger:strfmt date-time
 	PublishedAt time.Time `json:"published_at"`
+	// The user who published the release
 	Publisher *User `json:"author"`
+	// The files attached to the release
 	Attachments []*Attachment `json:"assets"`
 }
 
@@ -33,20 +47,32 @@ type Release struct {
 type CreateReleaseOption struct {
 	// required: true
 	TagName string `json:"tag_name" binding:"Required"`
+	// The message for the git tag
 	TagMessage string `json:"tag_message"`
+	// The target commitish for the release
 	Target string `json:"target_commitish"`
+	// The display title of the release
 	Title string `json:"name"`
+	// The release notes or description
 	Note string `json:"body"`
+	// Whether to create the release as a draft
 	IsDraft bool `json:"draft"`
+	// Whether to mark the release as a prerelease
 	IsPrerelease bool `json:"prerelease"`
 }
 
 // EditReleaseOption options when editing a release
 type EditReleaseOption struct {
+	// The new name of the git tag
 	TagName string `json:"tag_name"`
+	// The new target commitish for the release
 	Target string `json:"target_commitish"`
+	// The new display title of the release
 	Title string `json:"name"`
+	// The new release notes or description
 	Note string `json:"body"`
+	// Whether to change the draft status
 	IsDraft *bool `json:"draft"`
+	// Whether to change the prerelease status
 	IsPrerelease *bool `json:"prerelease"`
 }

modules/structs/repo_actions.go

@@ -9,15 +9,25 @@ import (
 
 // ActionTask represents a ActionTask
 type ActionTask struct {
+	// ID is the unique identifier for the action task
 	ID int64 `json:"id"`
+	// Name is the name of the workflow
 	Name string `json:"name"`
+	// HeadBranch is the branch that triggered the workflow
 	HeadBranch string `json:"head_branch"`
+	// HeadSHA is the commit SHA that triggered the workflow
 	HeadSHA string `json:"head_sha"`
+	// RunNumber is the sequential number of the workflow run
 	RunNumber int64 `json:"run_number"`
+	// Event is the type of event that triggered the workflow
 	Event string `json:"event"`
+	// DisplayTitle is the display title for the workflow run
 	DisplayTitle string `json:"display_title"`
+	// Status indicates the current status of the workflow run
 	Status string `json:"status"`
+	// WorkflowID is the identifier of the workflow
 	WorkflowID string `json:"workflow_id"`
+	// URL is the API URL for this workflow run
 	URL string `json:"url"`
 	// swagger:strfmt date-time
 	CreatedAt time.Time `json:"created_at"`
@@ -29,7 +39,9 @@ type ActionTask struct {
 
 // ActionTaskResponse returns a ActionTask
 type ActionTaskResponse struct {
+	// Entries contains the list of workflow runs
 	Entries []*ActionTask `json:"workflow_runs"`
+	// TotalCount is the total number of workflow runs
 	TotalCount int64 `json:"total_count"`
 }
 
@@ -45,16 +57,23 @@ type CreateActionWorkflowDispatch struct {
 
 // ActionWorkflow represents a ActionWorkflow
 type ActionWorkflow struct {
+	// ID is the unique identifier for the workflow
 	ID string `json:"id"`
+	// Name is the name of the workflow
 	Name string `json:"name"`
+	// Path is the file path of the workflow
 	Path string `json:"path"`
+	// State indicates if the workflow is active or disabled
 	State string `json:"state"`
 	// swagger:strfmt date-time
 	CreatedAt time.Time `json:"created_at"`
 	// swagger:strfmt date-time
 	UpdatedAt time.Time `json:"updated_at"`
+	// URL is the API URL for this workflow
 	URL string `json:"url"`
+	// HTMLURL is the web URL for viewing the workflow
 	HTMLURL string `json:"html_url"`
+	// BadgeURL is the URL for the workflow badge
 	BadgeURL string `json:"badge_url"`
 	// swagger:strfmt date-time
 	DeletedAt time.Time `json:"deleted_at"`

modules/structs/repo_branch.go

@@ -9,14 +9,23 @@ import (
 
 // Branch represents a repository branch
 type Branch struct {
+	// Name is the branch name
 	Name string `json:"name"`
+	// Commit contains the latest commit information for this branch
 	Commit *PayloadCommit `json:"commit"`
+	// Protected indicates if the branch is protected
 	Protected bool `json:"protected"`
+	// RequiredApprovals is the number of required approvals for pull requests
 	RequiredApprovals int64 `json:"required_approvals"`
+	// EnableStatusCheck indicates if status checks are enabled
 	EnableStatusCheck bool `json:"enable_status_check"`
+	// StatusCheckContexts contains the list of required status check contexts
 	StatusCheckContexts []string `json:"status_check_contexts"`
+	// UserCanPush indicates if the current user can push to this branch
 	UserCanPush bool `json:"user_can_push"`
+	// UserCanMerge indicates if the current user can merge to this branch
 	UserCanMerge bool `json:"user_can_merge"`
+	// EffectiveBranchProtectionName is the name of the effective branch protection rule
 	EffectiveBranchProtectionName string `json:"effective_branch_protection_name"`
 }
 
@@ -24,7 +33,9 @@ type Branch struct {
 type BranchProtection struct {
 	// Deprecated: true
 	BranchName string `json:"branch_name"`
+	// RuleName is the name of the branch protection rule
 	RuleName string `json:"rule_name"`
+	// Priority is the priority of this branch protection rule
 	Priority                      int64    `json:"priority"`
 	EnablePush                    bool     `json:"enable_push"`
 	EnablePushWhitelist           bool     `json:"enable_push_whitelist"`

modules/structs/repo_collaborator.go

@@ -6,12 +6,16 @@ package structs
 // AddCollaboratorOption options when adding a user as a collaborator of a repository
 type AddCollaboratorOption struct {
 	// enum: read,write,admin
+	// Permission level to grant the collaborator
 	Permission *string `json:"permission"`
 }
 
 // RepoCollaboratorPermission to get repository permission for a collaborator
 type RepoCollaboratorPermission struct {
+	// Permission level of the collaborator
 	Permission string `json:"permission"`
+	// RoleName is the name of the permission role
 	RoleName string `json:"role_name"`
+	// User information of the collaborator
 	User *User `json:"user"`
 }

modules/structs/repo_commit.go

@@ -10,64 +10,90 @@ import (
 
 // Identity for a person's identity like an author or committer
 type Identity struct {
+	// Name is the person's name
 	Name string `json:"name" binding:"MaxSize(100)"`
 	// swagger:strfmt email
+	// Email is the person's email address
 	Email string `json:"email" binding:"MaxSize(254)"`
 }
 
 // CommitMeta contains meta information of a commit in terms of API.
 type CommitMeta struct {
+	// URL is the API URL for the commit
 	URL string `json:"url"`
+	// SHA is the commit SHA hash
 	SHA string `json:"sha"`
 	// swagger:strfmt date-time
+	// Created is the time when the commit was created
 	Created time.Time `json:"created"`
 }
 
 // CommitUser contains information of a user in the context of a commit.
 type CommitUser struct {
 	Identity
+	// Date is the commit date in string format
 	Date string `json:"date"`
 }
 
 // RepoCommit contains information of a commit in the context of a repository.
 type RepoCommit struct {
+	// URL is the API URL for the commit
 	URL string `json:"url"`
+	// Author contains the commit author information
 	Author *CommitUser `json:"author"`
+	// Committer contains the commit committer information
 	Committer *CommitUser `json:"committer"`
+	// Message is the commit message
 	Message string `json:"message"`
+	// Tree contains the tree information for the commit
 	Tree *CommitMeta `json:"tree"`
+	// Verification contains commit signature verification information
 	Verification *PayloadCommitVerification `json:"verification"`
 }
 
 // CommitStats is statistics for a RepoCommit
 type CommitStats struct {
+	// Total is the total number of lines changed
 	Total int `json:"total"`
+	// Additions is the number of lines added
 	Additions int `json:"additions"`
+	// Deletions is the number of lines deleted
 	Deletions int `json:"deletions"`
 }
 
 // Commit contains information generated from a Git commit.
 type Commit struct {
 	*CommitMeta
+	// HTMLURL is the web URL for viewing the commit
 	HTMLURL string `json:"html_url"`
+	// RepoCommit contains the commit information
 	RepoCommit *RepoCommit `json:"commit"`
+	// Author is the GitHub/Gitea user who authored the commit
 	Author *User `json:"author"`
+	// Committer is the GitHub/Gitea user who committed the commit
 	Committer *User `json:"committer"`
+	// Parents contains the parent commit information
 	Parents []*CommitMeta `json:"parents"`
+	// Files contains information about files affected by the commit
 	Files []*CommitAffectedFiles `json:"files"`
+	// Stats contains statistics about the commit changes
 	Stats *CommitStats `json:"stats"`
 }
 
 // CommitDateOptions store dates for GIT_AUTHOR_DATE and GIT_COMMITTER_DATE
 type CommitDateOptions struct {
 	// swagger:strfmt date-time
+	// Author is the author date for the commit
 	Author time.Time `json:"author"`
 	// swagger:strfmt date-time
+	// Committer is the committer date for the commit
 	Committer time.Time `json:"committer"`
 }
 
 // CommitAffectedFiles store information about files affected by the commit
 type CommitAffectedFiles struct {
+	// Filename is the path of the affected file
 	Filename string `json:"filename"`
+	// Status indicates how the file was affected (added, modified, deleted)
 	Status string `json:"status"`
 }

modules/structs/repo_file.go

@@ -104,31 +104,42 @@ type ApplyDiffPatchFileOptions struct {
 
 // FileLinksResponse contains the links for a repo's file
 type FileLinksResponse struct {
+	// Self is the API URL for this file
 	Self *string `json:"self"`
+	// GitURL is the Git API URL for this file
 	GitURL *string `json:"git"`
+	// HTMLURL is the web URL for this file
 	HTMLURL *string `json:"html"`
 }
 
 type ContentsExtResponse struct {
+	// FileContents contains file information when the path represents a file
 	FileContents *ContentsResponse `json:"file_contents,omitempty"`
+	// DirContents contains directory listing when the path represents a directory
 	DirContents []*ContentsResponse `json:"dir_contents,omitempty"`
 }
 
 // ContentsResponse contains information about a repo's entry's (dir, file, symlink, submodule) metadata and content
 type ContentsResponse struct {
+	// Name is the file or directory name
 	Name string `json:"name"`
+	// Path is the full path to the file or directory
 	Path string `json:"path"`
+	// SHA is the Git blob or tree SHA
 	SHA string `json:"sha"`
 
+	// LastCommitSHA is the SHA of the last commit that affected this file
 	LastCommitSHA *string `json:"last_commit_sha,omitempty"`
 	// swagger:strfmt date-time
 	LastCommitterDate *time.Time `json:"last_committer_date,omitempty"`
 	// swagger:strfmt date-time
 	LastAuthorDate *time.Time `json:"last_author_date,omitempty"`
+	// LastCommitMessage is the message of the last commit that affected this file
 	LastCommitMessage *string `json:"last_commit_message,omitempty"`
 
 	// `type` will be `file`, `dir`, `symlink`, or `submodule`
 	Type string `json:"type"`
+	// Size is the file size in bytes
 	Size int64 `json:"size"`
 	// `encoding` is populated when `type` is `file`, otherwise null
 	Encoding *string `json:"encoding"`
@@ -136,51 +147,74 @@ type ContentsResponse struct {
 	Content *string `json:"content"`
 	// `target` is populated when `type` is `symlink`, otherwise null
 	Target *string `json:"target"`
+	// URL is the API URL for this file or directory
 	URL *string `json:"url"`
+	// HTMLURL is the web URL for this file or directory
 	HTMLURL *string `json:"html_url"`
+	// GitURL is the Git API URL for this blob or tree
 	GitURL *string `json:"git_url"`
+	// DownloadURL is the direct download URL for this file
 	DownloadURL *string `json:"download_url"`
 	// `submodule_git_url` is populated when `type` is `submodule`, otherwise null
 	SubmoduleGitURL *string `json:"submodule_git_url"`
+	// Links contains related URLs for this file or directory
 	Links *FileLinksResponse `json:"_links"`
 
+	// LfsOid is the Git LFS object ID if this file is stored in LFS
 	LfsOid *string `json:"lfs_oid,omitempty"`
+	// LfsSize is the file size if this file is stored in LFS
 	LfsSize *int64 `json:"lfs_size,omitempty"`
 }
 
 // FileCommitResponse contains information generated from a Git commit for a repo's file.
 type FileCommitResponse struct {
 	CommitMeta
+	// HTMLURL is the web URL for viewing this commit
 	HTMLURL string `json:"html_url"`
+	// Author is the commit author information
 	Author *CommitUser `json:"author"`
+	// Committer is the commit committer information
 	Committer *CommitUser `json:"committer"`
+	// Parents contains parent commit metadata
 	Parents []*CommitMeta `json:"parents"`
+	// Message is the commit message
 	Message string `json:"message"`
+	// Tree contains the tree metadata for this commit
 	Tree *CommitMeta `json:"tree"`
 }
 
 // FileResponse contains information about a repo's file
 type FileResponse struct {
+	// Content contains the file content and metadata
 	Content *ContentsResponse `json:"content"`
+	// Commit contains the commit information for this file operation
 	Commit *FileCommitResponse `json:"commit"`
+	// Verification contains the commit signature verification information
 	Verification *PayloadCommitVerification `json:"verification"`
 }
 
 // FilesResponse contains information about multiple files from a repo
 type FilesResponse struct {
+	// Files contains the list of file contents and metadata
 	Files []*ContentsResponse `json:"files"`
+	// Commit contains the commit information for this file operation
 	Commit *FileCommitResponse `json:"commit"`
+	// Verification contains the commit signature verification information
 	Verification *PayloadCommitVerification `json:"verification"`
 }
 
 // FileDeleteResponse contains information about a repo's file that was deleted
 type FileDeleteResponse struct {
+	// Content is always null for delete operations
 	Content any `json:"content"` // to be set to nil
+	// Commit contains the commit information for this delete operation
 	Commit *FileCommitResponse `json:"commit"`
+	// Verification contains the commit signature verification information
 	Verification *PayloadCommitVerification `json:"verification"`
 }
 
 // GetFilesOptions options for retrieving metadate and content of multiple files
 type GetFilesOptions struct {
+	// Files is the list of file paths to retrieve
 	Files []string `json:"files" binding:"Required"`
 }

modules/structs/repo_key.go

@@ -9,15 +9,24 @@ import (
 
 // DeployKey a deploy key
 type DeployKey struct {
+	// ID is the unique identifier for the deploy key
 	ID int64 `json:"id"`
+	// KeyID is the associated public key ID
 	KeyID int64 `json:"key_id"`
+	// Key contains the actual SSH key content
 	Key string `json:"key"`
+	// URL is the API URL for this deploy key
 	URL string `json:"url"`
+	// Title is the human-readable name for the key
 	Title string `json:"title"`
+	// Fingerprint is the key's fingerprint
 	Fingerprint string `json:"fingerprint"`
 	// swagger:strfmt date-time
+	// Created is the time when the deploy key was added
 	Created time.Time `json:"created_at"`
+	// ReadOnly indicates if the key has read-only access
 	ReadOnly bool `json:"read_only"`
+	// Repository is the repository this deploy key belongs to
 	Repository *Repository `json:"repository,omitempty"`
 }
 

modules/structs/repo_note.go

@@ -5,6 +5,8 @@ package structs
 
 // Note contains information related to a git note
 type Note struct {
+	// The content message of the git note
 	Message string `json:"message"`
+	// The commit that this note is attached to
 	Commit *Commit `json:"commit"`
 }

modules/structs/repo_refs.go

@@ -5,14 +5,20 @@ package structs
 
 // Reference represents a Git reference.
 type Reference struct {
+	// The name of the Git reference (e.g., refs/heads/main)
 	Ref string `json:"ref"`
+	// The URL to access this Git reference
 	URL string `json:"url"`
+	// The Git object that this reference points to
 	Object *GitObject `json:"object"`
 }
 
 // GitObject represents a Git object.
 type GitObject struct {
+	// The type of the Git object (e.g., commit, tag, tree, blob)
 	Type string `json:"type"`
+	// The SHA hash of the Git object
 	SHA string `json:"sha"`
+	// The URL to access this Git object
 	URL string `json:"url"`
 }

modules/structs/repo_tag.go

@@ -7,62 +7,93 @@ import "time"
 
 // Tag represents a repository tag
 type Tag struct {
+	// The name of the tag
 	Name string `json:"name"`
+	// The message associated with the tag
 	Message string `json:"message"`
+	// The ID (SHA) of the tag
 	ID string `json:"id"`
+	// The commit information associated with this tag
 	Commit *CommitMeta `json:"commit"`
+	// The URL to download the zipball archive
 	ZipballURL string `json:"zipball_url,omitempty"`
+	// The URL to download the tarball archive
 	TarballURL string `json:"tarball_url,omitempty"`
 }
 
 // AnnotatedTag represents an annotated tag
 type AnnotatedTag struct {
+	// The name of the annotated tag
 	Tag string `json:"tag"`
+	// The SHA hash of the annotated tag
 	SHA string `json:"sha"`
+	// The URL to access the annotated tag
 	URL string `json:"url"`
+	// The message associated with the annotated tag
 	Message string `json:"message"`
+	// The user who created the annotated tag
 	Tagger *CommitUser `json:"tagger"`
+	// The object that the annotated tag points to
 	Object *AnnotatedTagObject `json:"object"`
+	// The verification information for the annotated tag
 	Verification *PayloadCommitVerification `json:"verification"`
 }
 
 // AnnotatedTagObject contains meta information of the tag object
 type AnnotatedTagObject struct {
+	// The type of the tagged object (e.g., commit, tree)
 	Type string `json:"type"`
+	// The URL to access the tagged object
 	URL string `json:"url"`
+	// The SHA hash of the tagged object
 	SHA string `json:"sha"`
 }
 
 // CreateTagOption options when creating a tag
 type CreateTagOption struct {
 	// required: true
+	// The name of the tag to create
 	TagName string `json:"tag_name" binding:"Required"`
+	// The message to associate with the tag
 	Message string `json:"message"`
+	// The target commit SHA or branch name for the tag
 	Target string `json:"target"`
 }
 
 // TagProtection represents a tag protection
 type TagProtection struct {
+	// The unique identifier of the tag protection
 	ID int64 `json:"id"`
+	// The pattern to match tag names for protection
 	NamePattern string `json:"name_pattern"`
+	// List of usernames allowed to create/delete protected tags
 	WhitelistUsernames []string `json:"whitelist_usernames"`
+	// List of team names allowed to create/delete protected tags
 	WhitelistTeams []string `json:"whitelist_teams"`
 	// swagger:strfmt date-time
+	// The date and time when the tag protection was created
 	Created time.Time `json:"created_at"`
 	// swagger:strfmt date-time
+	// The date and time when the tag protection was last updated
 	Updated time.Time `json:"updated_at"`
 }
 
 // CreateTagProtectionOption options for creating a tag protection
 type CreateTagProtectionOption struct {
+	// The pattern to match tag names for protection
 	NamePattern string `json:"name_pattern"`
+	// List of usernames allowed to create/delete protected tags
 	WhitelistUsernames []string `json:"whitelist_usernames"`
+	// List of team names allowed to create/delete protected tags
 	WhitelistTeams []string `json:"whitelist_teams"`
 }
 
 // EditTagProtectionOption options for editing a tag protection
 type EditTagProtectionOption struct {
+	// The pattern to match tag names for protection
 	NamePattern *string `json:"name_pattern"`
+	// List of usernames allowed to create/delete protected tags
 	WhitelistUsernames []string `json:"whitelist_usernames"`
+	// List of team names allowed to create/delete protected tags
 	WhitelistTeams []string `json:"whitelist_teams"`
 }

modules/structs/repo_topic.go

@@ -9,15 +9,21 @@ import (
 
 // TopicResponse for returning topics
 type TopicResponse struct {
+	// The unique identifier of the topic
 	ID int64 `json:"id"`
+	// The name of the topic
 	Name string `json:"topic_name"`
+	// The number of repositories using this topic
 	RepoCount int `json:"repo_count"`
+	// The date and time when the topic was created
 	Created time.Time `json:"created"`
+	// The date and time when the topic was last updated
 	Updated time.Time `json:"updated"`
 }
 
 // TopicName a list of repo topic names
 type TopicName struct {
+	// List of topic names
 	TopicNames []string `json:"topics"`
 }
 

modules/structs/repo_tree.go

@@ -5,20 +5,32 @@ package structs
 
 // GitEntry represents a git tree
 type GitEntry struct {
+	// Path is the file or directory path
 	Path string `json:"path"`
+	// Mode is the file mode (permissions)
 	Mode string `json:"mode"`
+	// Type indicates if this is a file, directory, or symlink
 	Type string `json:"type"`
+	// Size is the file size in bytes
 	Size int64 `json:"size"`
+	// SHA is the Git object SHA
 	SHA string `json:"sha"`
+	// URL is the API URL for this tree entry
 	URL string `json:"url"`
 }
 
 // GitTreeResponse returns a git tree
 type GitTreeResponse struct {
+	// SHA is the tree object SHA
 	SHA string `json:"sha"`
+	// URL is the API URL for this tree
 	URL string `json:"url"`
+	// Entries contains the tree entries (files and directories)
 	Entries []GitEntry `json:"tree"`
+	// Truncated indicates if the response was truncated due to size
 	Truncated bool `json:"truncated"`
+	// Page is the current page number for pagination
 	Page int `json:"page"`
+	// TotalCount is the total number of entries in the tree
 	TotalCount int `json:"total_count"`
 }

modules/structs/repo_watch.go

@@ -9,10 +9,16 @@ import (
 
 // WatchInfo represents an API watch status of one repository
 type WatchInfo struct {
+	// Whether the repository is being watched for notifications
 	Subscribed bool `json:"subscribed"`
+	// Whether notifications for the repository are ignored
 	Ignored bool `json:"ignored"`
+	// The reason for the current watch status
 	Reason any `json:"reason"`
+	// The timestamp when the watch status was created
 	CreatedAt time.Time `json:"created_at"`
+	// The URL for managing the watch status
 	URL string `json:"url"`
+	// The URL of the repository being watched
 	RepositoryURL string `json:"repository_url"`
 }

modules/structs/repo_wiki.go

@@ -5,9 +5,13 @@ package structs
 
 // WikiCommit page commit/revision
 type WikiCommit struct {
+	// The commit SHA hash
 	ID string `json:"sha"`
+	// The author of the commit
 	Author *CommitUser `json:"author"`
+	// The committer of the commit
 	Committer *CommitUser `json:"commiter"`
+	// The commit message
 	Message string `json:"message"`
 }
 
@@ -16,16 +20,23 @@ type WikiPage struct {
 	*WikiPageMetaData
 	// Page content, base64 encoded
 	ContentBase64 string `json:"content_base64"`
+	// The number of commits that modified this page
 	CommitCount int64 `json:"commit_count"`
+	// The sidebar content for the wiki page
 	Sidebar string `json:"sidebar"`
+	// The footer content for the wiki page
 	Footer string `json:"footer"`
 }
 
 // WikiPageMetaData wiki page meta information
 type WikiPageMetaData struct {
+	// The title of the wiki page
 	Title string `json:"title"`
+	// The HTML URL to view the wiki page
 	HTMLURL string `json:"html_url"`
+	// The sub URL path for the wiki page
 	SubURL string `json:"sub_url"`
+	// The last commit that modified this wiki page
 	LastCommit *WikiCommit `json:"last_commit"`
 }
 
@@ -41,6 +52,8 @@ type CreateWikiPageOptions struct {
 
 // WikiCommitList commit/revision list
 type WikiCommitList struct {
+	// The list of wiki commits
 	WikiCommits []*WikiCommit `json:"commits"`
+	// The total count of commits
 	Count int64 `json:"count"`
 }

modules/structs/settings.go

@@ -5,34 +5,52 @@ package structs
 
 // GeneralRepoSettings contains global repository settings exposed by API
 type GeneralRepoSettings struct {
+	// MirrorsDisabled indicates if repository mirroring is disabled
 	MirrorsDisabled bool `json:"mirrors_disabled"`
+	// HTTPGitDisabled indicates if HTTP Git operations are disabled
 	HTTPGitDisabled bool `json:"http_git_disabled"`
+	// MigrationsDisabled indicates if repository migrations are disabled
 	MigrationsDisabled bool `json:"migrations_disabled"`
+	// StarsDisabled indicates if repository starring is disabled
 	StarsDisabled bool `json:"stars_disabled"`
+	// TimeTrackingDisabled indicates if time tracking is disabled
 	TimeTrackingDisabled bool `json:"time_tracking_disabled"`
+	// LFSDisabled indicates if Git LFS support is disabled
 	LFSDisabled bool `json:"lfs_disabled"`
 }
 
 // GeneralUISettings contains global ui settings exposed by API
 type GeneralUISettings struct {
+	// DefaultTheme is the default UI theme
 	DefaultTheme string `json:"default_theme"`
+	// AllowedReactions contains the list of allowed emoji reactions
 	AllowedReactions []string `json:"allowed_reactions"`
+	// CustomEmojis contains the list of custom emojis
 	CustomEmojis []string `json:"custom_emojis"`
 }
 
 // GeneralAPISettings contains global api settings exposed by it
 type GeneralAPISettings struct {
+	// MaxResponseItems is the maximum number of items returned in API responses
 	MaxResponseItems int `json:"max_response_items"`
+	// DefaultPagingNum is the default number of items per page
 	DefaultPagingNum int `json:"default_paging_num"`
+	// DefaultGitTreesPerPage is the default number of Git tree items per page
 	DefaultGitTreesPerPage int `json:"default_git_trees_per_page"`
+	// DefaultMaxBlobSize is the default maximum blob size for API responses
 	DefaultMaxBlobSize int64 `json:"default_max_blob_size"`
+	// DefaultMaxResponseSize is the default maximum response size
 	DefaultMaxResponseSize int64 `json:"default_max_response_size"`
 }
 
 // GeneralAttachmentSettings contains global Attachment settings exposed by API
 type GeneralAttachmentSettings struct {
+	// Enabled indicates if file attachments are enabled
 	Enabled bool `json:"enabled"`
+	// AllowedTypes contains the allowed file types for attachments
 	AllowedTypes string `json:"allowed_types"`
+	// MaxSize is the maximum size for individual attachments
 	MaxSize int64 `json:"max_size"`
+	// MaxFiles is the maximum number of files per attachment
 	MaxFiles int `json:"max_files"`
 }

modules/structs/status.go

@@ -11,12 +11,19 @@ import (
 
 // CommitStatus holds a single status of a single Commit
 type CommitStatus struct {
+	// ID is the unique identifier for the commit status
 	ID int64 `json:"id"`
+	// State represents the status state (pending, success, error, failure)
 	State commitstatus.CommitStatusState `json:"status"`
+	// TargetURL is the URL to link to for more details
 	TargetURL string `json:"target_url"`
+	// Description provides a brief description of the status
 	Description string `json:"description"`
+	// URL is the API URL for this status
 	URL string `json:"url"`
+	// Context is the unique context identifier for the status
 	Context string `json:"context"`
+	// Creator is the user who created the status
 	Creator *User `json:"creator"`
 	// swagger:strfmt date-time
 	Created time.Time `json:"created_at"`
@@ -26,19 +33,30 @@ type CommitStatus struct {
 
 // CombinedStatus holds the combined state of several statuses for a single commit
 type CombinedStatus struct {
+	// State is the overall combined status state
 	State commitstatus.CommitStatusState `json:"state"`
+	// SHA is the commit SHA this status applies to
 	SHA string `json:"sha"`
+	// TotalCount is the total number of statuses
 	TotalCount int `json:"total_count"`
+	// Statuses contains all individual commit statuses
 	Statuses []*CommitStatus `json:"statuses"`
+	// Repository is the repository this status belongs to
 	Repository *Repository `json:"repository"`
+	// CommitURL is the API URL for the commit
 	CommitURL string `json:"commit_url"`
+	// URL is the API URL for this combined status
 	URL string `json:"url"`
 }
 
 // CreateStatusOption holds the information needed to create a new CommitStatus for a Commit
 type CreateStatusOption struct {
+	// State represents the status state to set (pending, success, error, failure)
 	State commitstatus.CommitStatusState `json:"state"`
+	// TargetURL is the URL to link to for more details
 	TargetURL string `json:"target_url"`
+	// Description provides a brief description of the status
 	Description string `json:"description"`
+	// Context is the unique context identifier for the status
 	Context string `json:"context"`
 }

modules/structs/user_app.go

@@ -11,12 +11,19 @@ import (
 // AccessToken represents an API access token.
 // swagger:response AccessToken
 type AccessToken struct {
+	// The unique identifier of the access token
 	ID int64 `json:"id"`
+	// The name of the access token
 	Name string `json:"name"`
+	// The SHA1 hash of the access token
 	Token string `json:"sha1"`
+	// The last eight characters of the token
 	TokenLastEight string `json:"token_last_eight"`
+	// The scopes granted to this access token
 	Scopes []string `json:"scopes"`
+	// The timestamp when the token was created
 	Created time.Time `json:"created_at"`
+	// The timestamp when the token was last used
 	Updated time.Time `json:"last_used_at"`
 }
 
@@ -35,22 +42,34 @@ type CreateAccessTokenOption struct {
 
 // CreateOAuth2ApplicationOptions holds options to create an oauth2 application
 type CreateOAuth2ApplicationOptions struct {
+	// The name of the OAuth2 application
 	Name string `json:"name" binding:"Required"`
+	// Whether the client is confidential
 	ConfidentialClient bool `json:"confidential_client"`
+	// Whether to skip secondary authorization
 	SkipSecondaryAuthorization bool `json:"skip_secondary_authorization"`
+	// The list of allowed redirect URIs
 	RedirectURIs []string `json:"redirect_uris" binding:"Required"`
 }
 
 // OAuth2Application represents an OAuth2 application.
 // swagger:response OAuth2Application
 type OAuth2Application struct {
+	// The unique identifier of the OAuth2 application
 	ID int64 `json:"id"`
+	// The name of the OAuth2 application
 	Name string `json:"name"`
+	// The client ID of the OAuth2 application
 	ClientID string `json:"client_id"`
+	// The client secret of the OAuth2 application
 	ClientSecret string `json:"client_secret"`
+	// Whether the client is confidential
 	ConfidentialClient bool `json:"confidential_client"`
+	// Whether to skip secondary authorization
 	SkipSecondaryAuthorization bool `json:"skip_secondary_authorization"`
+	// The list of allowed redirect URIs
 	RedirectURIs []string `json:"redirect_uris"`
+	// The timestamp when the application was created
 	Created time.Time `json:"created"`
 }
 

modules/structs/user_email.go

@@ -7,9 +7,13 @@ package structs
 // Email an email address belonging to a user
 type Email struct {
 	// swagger:strfmt email
+	// The email address
 	Email string `json:"email"`
+	// Whether the email address has been verified
 	Verified bool `json:"verified"`
+	// Whether this is the primary email address
 	Primary bool `json:"primary"`
+	// The unique identifier of the user who owns this email
 	UserID int64 `json:"user_id"`
 	// username of the user
 	UserName string `json:"username"`

modules/structs/user_gpgkey.go

@@ -9,27 +9,42 @@ import (
 
 // GPGKey a user GPG key to sign commit and tag in repository
 type GPGKey struct {
+	// The unique identifier of the GPG key
 	ID int64 `json:"id"`
+	// The primary key ID of the GPG key
 	PrimaryKeyID string `json:"primary_key_id"`
+	// The key ID of the GPG key
 	KeyID string `json:"key_id"`
+	// The public key content in armored format
 	PublicKey string `json:"public_key"`
+	// List of email addresses associated with this GPG key
 	Emails []*GPGKeyEmail `json:"emails"`
+	// List of subkeys of this GPG key
 	SubsKey []*GPGKey `json:"subkeys"`
+	// Whether the key can be used for signing
 	CanSign bool `json:"can_sign"`
+	// Whether the key can be used for encrypting communications
 	CanEncryptComms bool `json:"can_encrypt_comms"`
+	// Whether the key can be used for encrypting storage
 	CanEncryptStorage bool `json:"can_encrypt_storage"`
+	// Whether the key can be used for certification
 	CanCertify bool `json:"can_certify"`
+	// Whether the GPG key has been verified
 	Verified bool `json:"verified"`
 	// swagger:strfmt date-time
+	// The date and time when the GPG key was created
 	Created time.Time `json:"created_at"`
 	// swagger:strfmt date-time
+	// The date and time when the GPG key expires
 	Expires time.Time `json:"expires_at"`
 }
 
 // GPGKeyEmail an email attached to a GPGKey
 // swagger:model GPGKeyEmail
 type GPGKeyEmail struct {
+	// The email address associated with the GPG key
 	Email string `json:"email"`
+	// Whether the email address has been verified
 	Verified bool `json:"verified"`
 }
 
@@ -40,6 +55,7 @@ type CreateGPGKeyOption struct {
 	// required: true
 	// unique: true
 	ArmoredKey string `json:"armored_public_key" binding:"Required"`
+	// An optional armored signature for the GPG key
 	Signature string `json:"armored_signature,omitempty"`
 }
 
@@ -48,6 +64,8 @@ type VerifyGPGKeyOption struct {
 	// An Signature for a GPG key token
 	//
 	// required: true
+	// The key ID of the GPG key to verify
 	KeyID string `json:"key_id" binding:"Required"`
+	// The armored signature to verify the GPG key
 	Signature string `json:"armored_signature" binding:"Required"`
 }

modules/structs/user_key.go

@@ -9,15 +9,25 @@ import (
 
 // PublicKey publickey is a user key to push code to repository
 type PublicKey struct {
+	// ID is the unique identifier for the public key
 	ID int64 `json:"id"`
+	// Key contains the actual SSH public key content
 	Key string `json:"key"`
+	// URL is the API URL for this key
 	URL string `json:"url,omitempty"`
+	// Title is the human-readable name for the key
 	Title string `json:"title,omitempty"`
+	// Fingerprint is the key's fingerprint
 	Fingerprint string `json:"fingerprint,omitempty"`
 	// swagger:strfmt date-time
+	// Created is the time when the key was added
 	Created time.Time `json:"created_at"`
+	// Updated is the time when the key was last used
 	Updated time.Time `json:"last_used_at"`
+	// Owner is the user who owns this key
 	Owner *User `json:"user,omitempty"`
+	// ReadOnly indicates if the key has read-only access
 	ReadOnly bool `json:"read_only,omitempty"`
+	// KeyType indicates the type of the SSH key
 	KeyType string `json:"key_type,omitempty"`
 }