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 {
-	ID     int64 `json:"id"`
+	// 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"`
+	OpType string `json:"op_type"`
-	ActUserID int64       `json:"act_user_id"`
+	// The ID of the user who performed the action
-	ActUser   *User       `json:"act_user"`
+	ActUserID int64 `json:"act_user_id"`
-	RepoID    int64       `json:"repo_id"`
+	// The user who performed the action
-	Repo      *Repository `json:"repo"`
+	ActUser *User `json:"act_user"`
-	CommentID int64       `json:"comment_id"`
+	// The ID of the repository associated with the activity
-	Comment   *Comment    `json:"comment"`
+	RepoID int64 `json:"repo_id"`
-	RefName   string      `json:"ref_name"`
+	// The repository associated with the activity
-	IsPrivate bool        `json:"is_private"`
+	Repo *Repository `json:"repo"`
-	Content   string      `json:"content"`
+	// The ID of the comment associated with the activity (if applicable)
-	Created   time.Time   `json:"created"`
+	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,15 +16,21 @@ 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)"`
+	Email string `json:"email" binding:"Required;Email;MaxSize(254)"`
-	Password           string `json:"password" binding:"MaxSize(255)"`
+	// The plain text password for the user
-	MustChangePassword *bool  `json:"must_change_password"`
+	Password string `json:"password" binding:"MaxSize(255)"`
-	SendNotify         bool   `json:"send_notify"`
+	// Whether the user must change password on first login
-	Restricted         *bool  `json:"restricted"`
+	MustChangePassword *bool `json:"must_change_password"`
-	Visibility         string `json:"visibility" binding:"In(,public,limited,private)"`
+	// 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
 	// migrated from other systems. When omitted, the user's creation timestamp
@@ -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
-	Email                   *string `json:"email" binding:"MaxSize(254)"`
+	// The email address of the user
-	FullName                *string `json:"full_name" binding:"MaxSize(100)"`
+	Email *string `json:"email" binding:"MaxSize(254)"`
-	Password                string  `json:"password" binding:"MaxSize(255)"`
+	// The full display name of the user
-	MustChangePassword      *bool   `json:"must_change_password"`
+	FullName *string `json:"full_name" binding:"MaxSize(100)"`
-	Website                 *string `json:"website" binding:"OmitEmpty;ValidUrl;MaxSize(255)"`
+	// The plain text password for the user
-	Location                *string `json:"location" binding:"MaxSize(50)"`
+	Password string `json:"password" binding:"MaxSize(255)"`
-	Description             *string `json:"description" binding:"MaxSize(255)"`
+	// Whether the user must change password on next login
-	Active                  *bool   `json:"active"`
+	MustChangePassword *bool `json:"must_change_password"`
-	Admin                   *bool   `json:"admin"`
+	// The user's personal website URL
-	AllowGitHook            *bool   `json:"allow_git_hook"`
+	Website *string `json:"website" binding:"OmitEmpty;ValidUrl;MaxSize(255)"`
-	AllowImportLocal        *bool   `json:"allow_import_local"`
+	// The user's location or address
-	MaxRepoCreation         *int    `json:"max_repo_creation"`
+	Location *string `json:"location" binding:"MaxSize(50)"`
-	ProhibitLogin           *bool   `json:"prohibit_login"`
+	// The user's personal description or bio
-	AllowCreateOrganization *bool   `json:"allow_create_organization"`
+	Description *string `json:"description" binding:"MaxSize(255)"`
-	Restricted              *bool   `json:"restricted"`
+	// Whether the user account is active
-	Visibility              string  `json:"visibility" binding:"In(,public,limited,private)"`
+	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            int64  `json:"id"`
+	// ID is the unique identifier for the attachment
-	Name          string `json:"name"`
+	ID int64 `json:"id"`
-	Size          int64  `json:"size"`
+	// Name is the filename of the attachment
-	DownloadCount int64  `json:"download_count"`
+	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     time.Time `json:"created_at"`
+	// Created is the time when the attachment was uploaded
-	UUID        string    `json:"uuid"`
+	Created time.Time `json:"created_at"`
-	DownloadURL string    `json:"browser_download_url"`
+	// 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 {
-	Name      string    `json:"name"`
+	// The name of the cron task
-	Schedule  string    `json:"schedule"`
+	Name string `json:"name"`
-	Next      time.Time `json:"next"`
+	// The cron schedule expression (e.g., "0 0 * * *")
-	Prev      time.Time `json:"prev"`
+	Schedule string `json:"schedule"`
-	ExecTimes int64     `json:"exec_times"`
+	// 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 {
-	Content  *string `json:"content"`
+	// 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"`
-	URL      string  `json:"url"`
+	// The URL to access this git blob
-	SHA      string  `json:"sha"`
+	URL string `json:"url"`
-	Size     int64   `json:"size"`
+	// The SHA hash of the git blob
+	SHA string `json:"sha"`
+	// The size of the git blob in bytes
+	Size int64 `json:"size"`
 
-	LfsOid  *string `json:"lfs_oid,omitempty"`
+	// The LFS object ID if this blob is stored in LFS
-	LfsSize *int64  `json:"lfs_size,omitempty"`
+	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,9 +5,12 @@ package structs
 
 // GitHook represents a Git repository hook
 type GitHook struct {
-	Name     string `json:"name"`
+	// Name is the name of the Git hook
-	IsActive bool   `json:"is_active"`
+	Name string `json:"name"`
-	Content  string `json:"content,omitempty"`
+	// 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"`
 }
 
 // GitHookList represents a list of Git hooks
@@ -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 {
-	ID                  int64             `json:"id"`
+	// The unique identifier of the webhook
-	Type                string            `json:"type"`
+	ID int64 `json:"id"`
-	BranchFilter        string            `json:"branch_filter"`
+	// The type of the webhook (e.g., gitea, slack, discord)
-	URL                 string            `json:"-"`
+	Type string `json:"type"`
-	Config              map[string]string `json:"config"`
+	// Branch filter pattern to determine which branches trigger the webhook
-	Events              []string          `json:"events"`
+	BranchFilter string `json:"branch_filter"`
-	AuthorizationHeader string            `json:"authorization_header"`
+	// The URL of the webhook endpoint (hidden in JSON)
-	Active              bool              `json:"active"`
+	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,23 +52,34 @@ 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
-	Config              CreateHookOptionConfig `json:"config" binding:"Required"`
+	// Configuration settings for the webhook
-	Events              []string               `json:"events"`
+	Config CreateHookOptionConfig `json:"config" binding:"Required"`
-	BranchFilter        string                 `json:"branch_filter" binding:"GlobPattern"`
+	// List of events that will trigger this webhook
-	AuthorizationHeader string                 `json:"authorization_header"`
+	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 {
-	Config              map[string]string `json:"config"`
+	// Configuration settings for the webhook
-	Events              []string          `json:"events"`
+	Config map[string]string `json:"config"`
-	BranchFilter        string            `json:"branch_filter" binding:"GlobPattern"`
+	// List of events that trigger this webhook
-	AuthorizationHeader string            `json:"authorization_header"`
+	Events []string `json:"events"`
-	Active              *bool             `json:"active"`
+	// 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"`
 }
 
 // Payloader payload is some part of one hook
@@ -82,26 +103,40 @@ type PayloadUser struct {
 // PayloadCommit represents a commit
 type PayloadCommit struct {
 	// sha1 hash of the commit
-	ID           string                     `json:"id"`
+	ID string `json:"id"`
-	Message      string                     `json:"message"`
+	// The commit message
-	URL          string                     `json:"url"`
+	Message string `json:"message"`
-	Author       *PayloadUser               `json:"author"`
+	// The URL to view this commit
-	Committer    *PayloadUser               `json:"committer"`
+	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"`
-	Added     []string  `json:"added"`
+	// List of files added in this commit
-	Removed   []string  `json:"removed"`
+	Added []string `json:"added"`
-	Modified  []string  `json:"modified"`
+	// 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 {
-	Verified  bool         `json:"verified"`
+	// Whether the commit signature is verified
-	Reason    string       `json:"reason"`
+	Verified bool `json:"verified"`
-	Signature string       `json:"signature"`
+	// The reason for the verification status
-	Signer    *PayloadUser `json:"signer"`
+	Reason string `json:"reason"`
-	Payload   string       `json:"payload"`
+	// 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"`
 }
 
 var (
@@ -119,11 +154,16 @@ var (
 
 // CreatePayload represents a payload information of create event.
 type CreatePayload struct {
-	Sha     string      `json:"sha"`
+	// The SHA hash of the created reference
-	Ref     string      `json:"ref"`
+	Sha string `json:"sha"`
-	RefType string      `json:"ref_type"`
+	// The full name of the created reference
-	Repo    *Repository `json:"repository"`
+	Ref string `json:"ref"`
-	Sender  *User       `json:"sender"`
+	// 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"`
 }
 
 // JSONPayload return payload information
@@ -161,11 +201,16 @@ const (
 
 // DeletePayload represents delete payload
 type DeletePayload struct {
-	Ref        string      `json:"ref"`
+	// The name of the deleted reference
-	RefType    string      `json:"ref_type"`
+	Ref string `json:"ref"`
-	PusherType PusherType  `json:"pusher_type"`
+	// The type of reference deleted (branch or tag)
-	Repo       *Repository `json:"repository"`
+	RefType string `json:"ref_type"`
-	Sender     *User       `json:"sender"`
+	// 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"`
 }
 
 // JSONPayload implements Payload
@@ -175,9 +220,12 @@ func (p *DeletePayload) JSONPayload() ([]byte, error) {
 
 // ForkPayload represents fork payload
 type ForkPayload struct {
+	// The forked repository (the new fork)
 	Forkee *Repository `json:"forkee"`
-	Repo   *Repository `json:"repository"`
+	// The original repository that was forked
-	Sender *User       `json:"sender"`
+	Repo *Repository `json:"repository"`
+	// The user who created the fork
+	Sender *User `json:"sender"`
 }
 
 // JSONPayload implements Payload
@@ -197,14 +245,22 @@ const (
 
 // IssueCommentPayload represents a payload information of issue comment event.
 type IssueCommentPayload struct {
-	Action      HookIssueCommentAction `json:"action"`
+	// The action performed on the comment (created, edited, deleted)
-	Issue       *Issue                 `json:"issue"`
+	Action HookIssueCommentAction `json:"action"`
-	PullRequest *PullRequest           `json:"pull_request,omitempty"`
+	// The issue that the comment belongs to
-	Comment     *Comment               `json:"comment"`
+	Issue *Issue `json:"issue"`
-	Changes     *ChangesPayload        `json:"changes,omitempty"`
+	// The pull request if the comment is on a pull request
-	Repository  *Repository            `json:"repository"`
+	PullRequest *PullRequest `json:"pull_request,omitempty"`
-	Sender      *User                  `json:"sender"`
+	// The comment that was acted upon
-	IsPull      bool                   `json:"is_pull"`
+	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"`
 }
 
 // JSONPayload implements Payload
@@ -224,10 +280,14 @@ const (
 
 // ReleasePayload represents a payload information of release event.
 type ReleasePayload struct {
-	Action     HookReleaseAction `json:"action"`
+	// The action performed on the release (published, updated, deleted)
-	Release    *Release          `json:"release"`
+	Action HookReleaseAction `json:"action"`
-	Repository *Repository       `json:"repository"`
+	// The release that was acted upon
-	Sender     *User             `json:"sender"`
+	Release *Release `json:"release"`
+	// The repository containing the release
+	Repository *Repository `json:"repository"`
+	// The user who performed the action
+	Sender *User `json:"sender"`
 }
 
 // JSONPayload implements Payload
@@ -237,16 +297,26 @@ func (p *ReleasePayload) JSONPayload() ([]byte, error) {
 
 // PushPayload represents a payload information of push event.
 type PushPayload struct {
-	Ref          string           `json:"ref"`
+	// The full name of the pushed reference
-	Before       string           `json:"before"`
+	Ref string `json:"ref"`
-	After        string           `json:"after"`
+	// The SHA of the most recent commit before the push
-	CompareURL   string           `json:"compare_url"`
+	Before string `json:"before"`
-	Commits      []*PayloadCommit `json:"commits"`
+	// The SHA of the most recent commit after the push
-	TotalCommits int              `json:"total_commits"`
+	After string `json:"after"`
-	HeadCommit   *PayloadCommit   `json:"head_commit"`
+	// URL to compare the changes in this push
-	Repo         *Repository      `json:"repository"`
+	CompareURL string `json:"compare_url"`
-	Pusher       *User            `json:"pusher"`
+	// List of commits included in the push
-	Sender       *User            `json:"sender"`
+	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"`
 }
 
 // JSONPayload FIXME
@@ -313,13 +383,20 @@ const (
 
 // IssuePayload represents the payload information that is sent along with an issue event.
 type IssuePayload struct {
-	Action     HookIssueAction `json:"action"`
+	// The action performed on the issue
-	Index      int64           `json:"number"`
+	Action HookIssueAction `json:"action"`
-	Changes    *ChangesPayload `json:"changes,omitempty"`
+	// The index number of the issue
-	Issue      *Issue          `json:"issue"`
+	Index int64 `json:"number"`
-	Repository *Repository     `json:"repository"`
+	// Changes made to the issue (for edit actions)
-	Sender     *User           `json:"sender"`
+	Changes *ChangesPayload `json:"changes,omitempty"`
-	CommitID   string          `json:"commit_id"`
+	// 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"`
 }
 
 // JSONPayload encodes the IssuePayload to JSON, with an indentation of two spaces.
@@ -329,27 +406,40 @@ 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"`
-	Body  *ChangesFromPayload `json:"body,omitempty"`
+	// Changes made to the body/description
-	Ref   *ChangesFromPayload `json:"ref,omitempty"`
+	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 {
-	Action            HookIssueAction `json:"action"`
+	// The action performed on the pull request
-	Index             int64           `json:"number"`
+	Action HookIssueAction `json:"action"`
-	Changes           *ChangesPayload `json:"changes,omitempty"`
+	// The index number of the pull request
-	PullRequest       *PullRequest    `json:"pull_request"`
+	Index int64 `json:"number"`
-	RequestedReviewer *User           `json:"requested_reviewer"`
+	// Changes made to the pull request (for edit actions)
-	Repository        *Repository     `json:"repository"`
+	Changes *ChangesPayload `json:"changes,omitempty"`
-	Sender            *User           `json:"sender"`
+	// The pull request that was acted upon
-	CommitID          string          `json:"commit_id"`
+	PullRequest *PullRequest `json:"pull_request"`
-	Review            *ReviewPayload  `json:"review"`
+	// 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"`
 }
 
 // JSONPayload FIXME
@@ -359,7 +449,9 @@ func (p *PullRequestPayload) JSONPayload() ([]byte, error) {
 
 // ReviewPayload FIXME
 type ReviewPayload struct {
-	Type    string `json:"type"`
+	// The type of review (approved, rejected, comment)
+	Type string `json:"type"`
+	// The content/body of the review
 	Content string `json:"content"`
 }
 
@@ -377,11 +469,16 @@ const (
 
 // WikiPayload payload for repository webhooks
 type WikiPayload struct {
-	Action     HookWikiAction `json:"action"`
+	// The action performed on the wiki page
-	Repository *Repository    `json:"repository"`
+	Action HookWikiAction `json:"action"`
-	Sender     *User          `json:"sender"`
+	// The repository containing the wiki
-	Page       string         `json:"page"`
+	Repository *Repository `json:"repository"`
-	Comment    string         `json:"comment"`
+	// 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"`
 }
 
 // JSONPayload JSON representation of the payload
@@ -401,10 +498,14 @@ const (
 
 // RepositoryPayload payload for repository webhooks
 type RepositoryPayload struct {
-	Action       HookRepoAction `json:"action"`
+	// The action performed on the repository
-	Repository   *Repository    `json:"repository"`
+	Action HookRepoAction `json:"action"`
-	Organization *User          `json:"organization"`
+	// The repository that was acted upon
-	Sender       *User          `json:"sender"`
+	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"`
 }
 
 // JSONPayload JSON representation of the payload
@@ -424,11 +525,16 @@ const (
 
 // PackagePayload represents a package payload
 type PackagePayload struct {
-	Action       HookPackageAction `json:"action"`
+	// The action performed on the package
-	Repository   *Repository       `json:"repository"`
+	Action HookPackageAction `json:"action"`
-	Package      *Package          `json:"package"`
+	// The repository associated with the package
-	Organization *Organization     `json:"organization"`
+	Repository *Repository `json:"repository"`
-	Sender       *User             `json:"sender"`
+	// 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"`
 }
 
 // JSONPayload implements Payload
@@ -438,11 +544,16 @@ func (p *PackagePayload) JSONPayload() ([]byte, error) {
 
 // WorkflowDispatchPayload represents a workflow dispatch payload
 type WorkflowDispatchPayload struct {
-	Workflow   string         `json:"workflow"`
+	// The name or path of the workflow file
-	Ref        string         `json:"ref"`
+	Workflow string `json:"workflow"`
-	Inputs     map[string]any `json:"inputs"`
+	// The git reference (branch, tag, or commit SHA) to run the workflow on
-	Repository *Repository    `json:"repository"`
+	Ref string `json:"ref"`
-	Sender     *User          `json:"sender"`
+	// 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"`
 }
 
 // JSONPayload implements Payload
@@ -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
-	Commit  *PayloadCommit `json:"commit"`
+	// The commit that the status is associated with
-	Context string         `json:"context"`
+	Commit *PayloadCommit `json:"commit"`
+	// The context/identifier for this status check
+	Context string `json:"context"`
 	// swagger:strfmt date-time
-	CreatedAt   time.Time   `json:"created_at"`
+	// The date and time when the status was created
-	Description string      `json:"description"`
+	CreatedAt time.Time `json:"created_at"`
-	ID          int64       `json:"id"`
+	// A short description of the status
-	Repo        *Repository `json:"repository"`
+	Description string `json:"description"`
-	Sender      *User       `json:"sender"`
+	// The unique identifier of the status
-	SHA         string      `json:"sha"`
+	ID int64 `json:"id"`
-	State       string      `json:"state"`
+	// The repository containing the commit
-	TargetURL   string      `json:"target_url"`
+	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,13 +597,20 @@ func (p *CommitStatusPayload) JSONPayload() ([]byte, error) {
 
 // WorkflowRunPayload represents a payload information of workflow run event.
 type WorkflowRunPayload struct {
-	Action       string             `json:"action"`
+	// The action performed on the workflow run
-	Workflow     *ActionWorkflow    `json:"workflow"`
+	Action string `json:"action"`
-	WorkflowRun  *ActionWorkflowRun `json:"workflow_run"`
+	// The workflow definition
-	PullRequest  *PullRequest       `json:"pull_request,omitempty"`
+	Workflow *ActionWorkflow `json:"workflow"`
-	Organization *Organization      `json:"organization,omitempty"`
+	// The workflow run that was acted upon
-	Repo         *Repository        `json:"repository"`
+	WorkflowRun *ActionWorkflowRun `json:"workflow_run"`
-	Sender       *User              `json:"sender"`
+	// 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"`
 }
 
 // JSONPayload implements Payload
@@ -491,12 +620,18 @@ func (p *WorkflowRunPayload) JSONPayload() ([]byte, error) {
 
 // WorkflowJobPayload represents a payload information of workflow job event.
 type WorkflowJobPayload struct {
-	Action       string             `json:"action"`
+	// The action performed on the workflow job
-	WorkflowJob  *ActionWorkflowJob `json:"workflow_job"`
+	Action string `json:"action"`
-	PullRequest  *PullRequest       `json:"pull_request,omitempty"`
+	// The workflow job that was acted upon
-	Organization *Organization      `json:"organization,omitempty"`
+	WorkflowJob *ActionWorkflowJob `json:"workflow_job"`
-	Repo         *Repository        `json:"repository"`
+	// The pull request associated with the workflow job (if applicable)
-	Sender       *User              `json:"sender"`
+	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"`
 }
 
 // JSONPayload implements Payload

modules/structs/issue_comment.go

@@ -9,15 +9,24 @@ import (
 
 // Comment represents a comment on a commit or issue
 type Comment struct {
-	ID               int64         `json:"id"`
+	// ID is the unique identifier for the comment
-	HTMLURL          string        `json:"html_url"`
+	ID int64 `json:"id"`
-	PRURL            string        `json:"pull_request_url"`
+	// HTMLURL is the web URL for viewing the comment
-	IssueURL         string        `json:"issue_url"`
+	HTMLURL string `json:"html_url"`
-	Poster           *User         `json:"user"`
+	// PRURL is the API URL for the pull request (if applicable)
-	OriginalAuthor   string        `json:"original_author"`
+	PRURL string `json:"pull_request_url"`
-	OriginalAuthorID int64         `json:"original_author_id"`
+	// IssueURL is the API URL for the issue
-	Body             string        `json:"body"`
+	IssueURL string `json:"issue_url"`
-	Attachments      []*Attachment `json:"assets"`
+	// 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"`
 	// swagger:strfmt date-time
@@ -27,25 +36,34 @@ 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   int64  `json:"id"`
+	// 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  string `json:"html_url"`
+	// HTMLURL is the web URL for viewing the comment
-	PRURL    string `json:"pull_request_url"`
+	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   *User  `json:"user"`
+	// Poster is the user who created the timeline event
-	Body     string `json:"body"`
+	Poster *User `json:"user"`
+	// Body contains the timeline event content
+	Body string `json:"body"`
 	// swagger:strfmt date-time
 	Created time.Time `json:"created_at"`
 	// swagger:strfmt date-time

modules/structs/issue_label.go

@@ -7,27 +7,33 @@ package structs
 // Label a label to an issue or a pr
 // swagger:model
 type Label struct {
-	ID   int64  `json:"id"`
+	// 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"`
 	// example: false
 	IsArchived bool `json:"is_archived"`
 	// example: 00aabb
-	Color       string `json:"color"`
+	Color string `json:"color"`
+	// Description provides additional context about the label's purpose
 	Description string `json:"description"`
-	URL         string `json:"url"`
+	// 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"`
+	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"`
+	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"`
+	Color string `json:"color"`
+	// Description provides additional context about the label template's purpose
 	Description string `json:"description"`
 }

modules/structs/issue_milestone.go

@@ -9,12 +9,18 @@ import (
 
 // Milestone milestone is a collection of issues on one repository
 type Milestone struct {
-	ID           int64     `json:"id"`
+	// ID is the unique identifier for the milestone
-	Title        string    `json:"title"`
+	ID int64 `json:"id"`
-	Description  string    `json:"description"`
+	// Title is the title of the milestone
-	State        StateType `json:"state"`
+	Title string `json:"title"`
-	OpenIssues   int       `json:"open_issues"`
+	// Description provides details about the milestone
-	ClosedIssues int       `json:"closed_issues"`
+	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"`
 	// swagger:strfmt date-time
@@ -27,18 +33,26 @@ type Milestone struct {
 
 // CreateMilestoneOption options for creating a milestone
 type CreateMilestoneOption struct {
-	Title       string `json:"title"`
+	// 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       string     `json:"title"`
+	// Title is the updated title of the milestone
-	Description *string    `json:"description"`
+	Title string `json:"title"`
-	State       *string    `json:"state"`
+	// Description provides updated details about the milestone
-	Deadline    *time.Time `json:"due_on"`
+	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 {
-	User     *User  `json:"user"`
+	// 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,13 +10,20 @@ import (
 // StopWatch represent a running stopwatch
 type StopWatch struct {
 	// swagger:strfmt date-time
-	Created       time.Time `json:"created"`
+	// Created is the time when the stopwatch was started
-	Seconds       int64     `json:"seconds"`
+	Created time.Time `json:"created"`
-	Duration      string    `json:"duration"`
+	// Seconds is the total elapsed time in seconds
-	IssueIndex    int64     `json:"issue_index"`
+	Seconds int64 `json:"seconds"`
-	IssueTitle    string    `json:"issue_title"`
+	// Duration is a human-readable duration string
-	RepoOwnerName string    `json:"repo_owner_name"`
+	Duration string `json:"duration"`
-	RepoName      string    `json:"repo_name"`
+	// 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"`
 }
 
 // StopWatches represent a list of stopwatches

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"`
@@ -30,8 +31,9 @@ type TrackedTime struct {
 	// username of the user
 	UserName string `json:"user_name"`
 	// deprecated (only for backwards compatibility)
-	IssueID int64  `json:"issue_id"`
+	IssueID int64 `json:"issue_id"`
-	Issue   *Issue `json:"issue"`
+	// Issue contains the associated issue information
+	Issue *Issue `json:"issue"`
 }
 
 // TrackedTimeList represents a list of tracked times

modules/structs/lfs_lock.go

@@ -10,55 +10,72 @@ import (
 // LFSLock represent a lock
 // for use with the locks API.
 type LFSLock struct {
-	ID       string        `json:"id"`
+	// The unique identifier of the lock
-	Path     string        `json:"path"`
+	ID string `json:"id"`
-	LockedAt time.Time     `json:"locked_at"`
+	// The file path that is locked
-	Owner    *LFSLockOwner `json:"owner"`
+	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"`
-	Next  string     `json:"next_cursor,omitempty"`
+	// 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 {
-	Ours   []*LFSLock `json:"ours"`
+	// Locks owned by the requesting user
+	Ours []*LFSLock `json:"ours"`
+	// Locks owned by other users
 	Theirs []*LFSLock `json:"theirs"`
-	Next   string     `json:"next_cursor,omitempty"`
+	// 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 {
-	Message       string   `json:"message"`
+	// The error message
-	Lock          *LFSLock `json:"lock,omitempty"`
+	Message string `json:"message"`
-	Documentation string   `json:"documentation_url,omitempty"`
+	// The lock related to the error, if any
-	RequestID     string   `json:"request_id,omitempty"`
+	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 {
-	RemoteAddress  string `json:"remote_address"`
+	// 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"`
-	Interval       string `json:"interval"`
+	// The sync interval for automatic updates
-	SyncOnCommit   bool   `json:"sync_on_commit"`
+	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 {
-	RepoName      string `json:"repo_name"`
+	// The name of the source repository
-	RemoteName    string `json:"remote_name"`
+	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"`
-	LastError      string     `json:"last_error"`
+	// The last error message encountered during sync
-	Interval       string     `json:"interval"`
+	LastError string `json:"last_error"`
-	SyncOnCommit   bool       `json:"sync_on_commit"`
+	// 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   bool          `json:"ok"`
+	// 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    bool   `json:"ok"`
+	// 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   string `json:"name"`
+	// 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  string `json:"key"`
+	// 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  string `json:"url"`
+	// URL is the reference URL for the license
+	URL string `json:"url"`
 }
 
 // LicensesInfo contains information about a License
 type LicenseTemplateInfo struct {
-	Key            string `json:"key"`
+	// Key is the unique identifier for the license template
-	Name           string `json:"name"`
+	Key string `json:"key"`
-	URL            string `json:"url"`
+	// 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           string `json:"body"`
+	// 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     string `json:"url"`
+	// 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           string           `json:"version"`
+	// Version specifies the schema version
-	Software          NodeInfoSoftware `json:"software"`
+	Version string `json:"version"`
-	Protocols         []string         `json:"protocols"`
+	// Software contains information about the server software
-	Services          NodeInfoServices `json:"services"`
+	Software NodeInfoSoftware `json:"software"`
-	OpenRegistrations bool             `json:"openRegistrations"`
+	// Protocols lists the protocols supported by this server
-	Usage             NodeInfoUsage    `json:"usage"`
+	Protocols []string `json:"protocols"`
-	Metadata          struct{}         `json:"metadata"`
+	// 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       string `json:"name"`
+	// Name is the canonical name of this server software
-	Version    string `json:"version"`
+	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   string `json:"homepage"`
+	// 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  []string `json:"inbound"`
+	// 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         NodeInfoUsageUsers `json:"users"`
+	// Users contains user statistics
-	LocalPosts    int                `json:"localPosts,omitempty"`
+	Users NodeInfoUsageUsers `json:"users"`
-	LocalComments int                `json:"localComments,omitempty"`
+	// 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          int `json:"total,omitempty"`
+	// 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    int `json:"activeMonth,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         int64                `json:"id"`
+	// ID is the unique identifier for the notification thread
-	Repository *Repository          `json:"repository"`
+	ID int64 `json:"id"`
-	Subject    *NotificationSubject `json:"subject"`
+	// Repository is the repository associated with the notification
-	Unread     bool                 `json:"unread"`
+	Repository *Repository `json:"repository"`
-	Pinned     bool                 `json:"pinned"`
+	// Subject contains details about the notification subject
-	UpdatedAt  time.Time            `json:"updated_at"`
+	Subject *NotificationSubject `json:"subject"`
-	URL        string               `json:"url"`
+	// 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                string            `json:"title"`
+	// Title is the title of the notification subject
-	URL                  string            `json:"url"`
+	Title string `json:"title"`
-	LatestCommentURL     string            `json:"latest_comment_url"`
+	// URL is the API URL for the notification subject
-	HTMLURL              string            `json:"html_url"`
+	URL string `json:"url"`
-	LatestCommentHTMLURL string            `json:"latest_comment_html_url"`
+	// LatestCommentURL is the API URL for the latest comment
-	Type                 NotifySubjectType `json:"type" binding:"In(Issue,Pull,Commit,Repository)"`
+	LatestCommentURL string `json:"latest_comment_url"`
-	State                StateType         `json:"state"`
+	// 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,16 +5,26 @@ package structs
 
 // Organization represents an organization
 type Organization struct {
-	ID                        int64  `json:"id"`
+	// The unique identifier of the organization
-	Name                      string `json:"name"`
+	ID int64 `json:"id"`
-	FullName                  string `json:"full_name"`
+	// The name of the organization
-	Email                     string `json:"email"`
+	Name string `json:"name"`
-	AvatarURL                 string `json:"avatar_url"`
+	// The full display name of the organization
-	Description               string `json:"description"`
+	FullName string `json:"full_name"`
-	Website                   string `json:"website"`
+	// The email address of the organization
-	Location                  string `json:"location"`
+	Email string `json:"email"`
-	Visibility                string `json:"visibility"`
+	// The URL of the organization's avatar
-	RepoAdminChangeTeamAccess bool   `json:"repo_admin_change_team_access"`
+	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
 	UserName string `json:"username"`
@@ -22,10 +32,15 @@ type Organization struct {
 
 // OrganizationPermissions list different users permissions on an organization
 type OrganizationPermissions struct {
-	IsOwner             bool `json:"is_owner"`
+	// Whether the user is an owner of the organization
-	IsAdmin             bool `json:"is_admin"`
+	IsOwner bool `json:"is_owner"`
-	CanWrite            bool `json:"can_write"`
+	// Whether the user is an admin of the organization
-	CanRead             bool `json:"can_read"`
+	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"`
 }
 
@@ -33,31 +48,43 @@ type OrganizationPermissions struct {
 type CreateOrgOption struct {
 	// username of the organization
 	// required: true
-	UserName    string `json:"username" binding:"Required;Username;MaxSize(40)"`
+	UserName string `json:"username" binding:"Required;Username;MaxSize(40)"`
-	FullName    string `json:"full_name" binding:"MaxSize(100)"`
+	// The full display name of the organization
-	Email       string `json:"email" binding:"MaxSize(255)"`
+	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)"`
-	Website     string `json:"website" binding:"ValidUrl;MaxSize(255)"`
+	// The website URL of the organization
-	Location    string `json:"location" binding:"MaxSize(50)"`
+	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)"`
+	Visibility string `json:"visibility" binding:"In(,public,limited,private)"`
-	RepoAdminChangeTeamAccess bool   `json:"repo_admin_change_team_access"`
+	// Whether repository administrators can change team access
+	RepoAdminChangeTeamAccess bool `json:"repo_admin_change_team_access"`
 }
 
 // TODO: make EditOrgOption fields optional after https://gitea.com/go-chi/binding/pulls/5 got merged
 
 // EditOrgOption options for editing an organization
 type EditOrgOption struct {
-	FullName    string `json:"full_name" binding:"MaxSize(100)"`
+	// The full display name of the organization
-	Email       string `json:"email" binding:"MaxSize(255)"`
+	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)"`
-	Website     string `json:"website" binding:"ValidUrl;MaxSize(255)"`
+	// The website URL of the organization
-	Location    string `json:"location" binding:"MaxSize(50)"`
+	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)"`
+	Visibility string `json:"visibility" binding:"In(,public,limited,private)"`
-	RepoAdminChangeTeamAccess *bool  `json:"repo_admin_change_team_access"`
+	// Whether repository administrators can change team access
+	RepoAdminChangeTeamAccess *bool `json:"repo_admin_change_team_access"`
 }
 
 // RenameOrgOption options when renaming an organization

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,49 +6,61 @@ package structs
 
 // Team represents a team in an organization
 type Team struct {
-	ID                      int64         `json:"id"`
+	// The unique identifier of the team
-	Name                    string        `json:"name"`
+	ID int64 `json:"id"`
-	Description             string        `json:"description"`
+	// The name of the team
-	Organization            *Organization `json:"organization"`
+	Name string `json:"name"`
-	IncludesAllRepositories bool          `json:"includes_all_repositories"`
+	// 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"`
 	// example: ["repo.code","repo.issues","repo.ext_issues","repo.wiki","repo.pulls","repo.releases","repo.projects","repo.ext_wiki"]
 	// Deprecated: This variable should be replaced by UnitsMap and will be dropped in later versions.
 	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"`
+	UnitsMap map[string]string `json:"units_map"`
-	CanCreateOrgRepo bool              `json:"can_create_org_repo"`
+	// Whether the team can create repositories in the organization
+	CanCreateOrgRepo bool `json:"can_create_org_repo"`
 }
 
 // CreateTeamOption options for creating a team
 type CreateTeamOption struct {
 	// required: true
-	Name                    string `json:"name" binding:"Required;AlphaDashDot;MaxSize(255)"`
+	Name string `json:"name" binding:"Required;AlphaDashDot;MaxSize(255)"`
-	Description             string `json:"description" binding:"MaxSize(255)"`
+	// The description of the team
-	IncludesAllRepositories bool   `json:"includes_all_repositories"`
+	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"`
 	// example: ["repo.actions","repo.code","repo.issues","repo.ext_issues","repo.wiki","repo.ext_wiki","repo.pulls","repo.releases","repo.projects","repo.ext_wiki"]
 	// Deprecated: This variable should be replaced by UnitsMap and will be dropped in later versions.
 	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"`
+	UnitsMap map[string]string `json:"units_map"`
-	CanCreateOrgRepo bool              `json:"can_create_org_repo"`
+	// Whether the team can create repositories in the organization
+	CanCreateOrgRepo bool `json:"can_create_org_repo"`
 }
 
 // EditTeamOption options for editing a team
 type EditTeamOption struct {
 	// required: true
-	Name                    string  `json:"name" binding:"AlphaDashDot;MaxSize(255)"`
+	Name string `json:"name" binding:"AlphaDashDot;MaxSize(255)"`
-	Description             *string `json:"description" binding:"MaxSize(255)"`
+	// The description of the team
-	IncludesAllRepositories *bool   `json:"includes_all_repositories"`
+	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"`
 	// example: ["repo.code","repo.issues","repo.ext_issues","repo.wiki","repo.pulls","repo.releases","repo.projects","repo.ext_wiki"]
 	// Deprecated: This variable should be replaced by UnitsMap and will be dropped in later versions.
 	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"`
+	UnitsMap map[string]string `json:"units_map"`
-	CanCreateOrgRepo *bool             `json:"can_create_org_repo"`
+	// 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 {
-	ID         int64       `json:"id"`
+	// The unique identifier of the package
-	Owner      *User       `json:"owner"`
+	ID int64 `json:"id"`
+	// The owner of the package
+	Owner *User `json:"owner"`
+	// The repository that contains this package
 	Repository *Repository `json:"repository"`
-	Creator    *User       `json:"creator"`
+	// The user who created this package
-	Type       string      `json:"type"`
+	Creator *User `json:"creator"`
-	Name       string      `json:"name"`
+	// The type of the package (e.g., npm, maven, docker)
-	Version    string      `json:"version"`
+	Type string `json:"type"`
-	HTMLURL    string      `json:"html_url"`
+	// 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 {
-	ID         int64  `json:"id"`
+	// The unique identifier of the package file
-	Size       int64  `json:"size"`
+	ID int64 `json:"id"`
-	Name       string `json:"name"`
+	// The size of the package file in bytes
-	HashMD5    string `json:"md5"`
+	Size int64 `json:"size"`
-	HashSHA1   string `json:"sha1"`
+	// 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,45 +9,75 @@ import (
 
 // PullRequest represents a pull request
 type PullRequest struct {
-	ID                      int64      `json:"id"`
+	// The unique identifier of the pull request
-	URL                     string     `json:"url"`
+	ID int64 `json:"id"`
-	Index                   int64      `json:"number"`
+	// The API URL of the pull request
-	Poster                  *User      `json:"user"`
+	URL string `json:"url"`
-	Title                   string     `json:"title"`
+	// The pull request number
-	Body                    string     `json:"body"`
+	Index int64 `json:"number"`
-	Labels                  []*Label   `json:"labels"`
+	// The user who created the pull request
-	Milestone               *Milestone `json:"milestone"`
+	Poster *User `json:"user"`
-	Assignee                *User      `json:"assignee"`
+	// The title of the pull request
-	Assignees               []*User    `json:"assignees"`
+	Title string `json:"title"`
-	RequestedReviewers      []*User    `json:"requested_reviewers"`
+	// The description body of the pull request
-	RequestedReviewersTeams []*Team    `json:"requested_reviewers_teams"`
+	Body string `json:"body"`
-	State                   StateType  `json:"state"`
+	// The labels attached to the pull request
-	Draft                   bool       `json:"draft"`
+	Labels []*Label `json:"labels"`
-	IsLocked                bool       `json:"is_locked"`
+	// The milestone associated with the pull request
-	Comments                int        `json:"comments"`
+	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"`
 
-	Additions    *int `json:"additions,omitempty"`
+	// The number of lines added in the pull request
-	Deletions    *int `json:"deletions,omitempty"`
+	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"`
 
-	HTMLURL  string `json:"html_url"`
+	// The HTML URL to view the pull request
-	DiffURL  string `json:"diff_url"`
+	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"`
+	Merged *time.Time `json:"merged_at"`
-	MergedCommitID      *string    `json:"merge_commit_sha"`
+	// The SHA of the merge commit
-	MergedBy            *User      `json:"merged_by"`
+	MergedCommitID *string `json:"merge_commit_sha"`
-	AllowMaintainerEdit bool       `json:"allow_maintainer_edit"`
+	// 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"`
 
-	Base      *PRBranchInfo `json:"base"`
+	// Information about the base branch
-	Head      *PRBranchInfo `json:"head"`
+	Base *PRBranchInfo `json:"base"`
-	MergeBase string        `json:"merge_base"`
+	// Information about the head branch
+	Head *PRBranchInfo `json:"head"`
+	// The merge base commit SHA
+	MergeBase string `json:"merge_base"`
 
 	// swagger:strfmt date-time
 	Deadline *time.Time `json:"due_date"`
@@ -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 {
-	Name       string      `json:"label"`
+	// The display name of the branch
-	Ref        string      `json:"ref"`
+	Name string `json:"label"`
-	Sha        string      `json:"sha"`
+	// The git reference of the branch
-	RepoID     int64       `json:"repo_id"`
+	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 {
-	Page  int    `json:"page"`
+	// 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 {
-	Head      string   `json:"head" binding:"Required"`
+	// The head branch for the pull request, it could be a branch name on the base repository or
-	Base      string   `json:"base" binding:"Required"`
+	// a form like `<username>:<branch>` which refers to the user's fork repository's branch.
-	Title     string   `json:"title" binding:"Required"`
+	Head string `json:"head" binding:"Required"`
-	Body      string   `json:"body"`
+	// The base branch for the pull request
-	Assignee  string   `json:"assignee"`
+	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"`
-	Milestone int64    `json:"milestone"`
+	// The milestone ID to assign to the pull request
-	Labels    []int64  `json:"labels"`
+	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"`
+	Deadline *time.Time `json:"due_date"`
-	Reviewers     []string   `json:"reviewers"`
+	// The list of reviewer usernames
-	TeamReviewers []string   `json:"team_reviewers"`
+	Reviewers []string `json:"reviewers"`
+	// The list of team reviewer names
+	TeamReviewers []string `json:"team_reviewers"`
 }
 
 // EditPullRequestOption options when modify pull request
 type EditPullRequestOption struct {
-	Title     string   `json:"title"`
+	// The new title for the pull request
-	Body      *string  `json:"body"`
+	Title string `json:"title"`
-	Base      string   `json:"base"`
+	// The new description body for the pull request
-	Assignee  string   `json:"assignee"`
+	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"`
-	Milestone int64    `json:"milestone"`
+	// The new milestone ID for the pull request
-	Labels    []int64  `json:"labels"`
+	Milestone int64 `json:"milestone"`
-	State     *string  `json:"state"`
+	// 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"`
+	Deadline *time.Time `json:"due_date"`
-	RemoveDeadline      *bool      `json:"unset_due_date"`
+	// Whether to remove the current deadline
-	AllowMaintainerEdit *bool      `json:"allow_maintainer_edit"`
+	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 {
-	Filename         string `json:"filename"`
+	// The name of the changed file
+	Filename string `json:"filename"`
+	// The previous filename if the file was renamed
 	PreviousFilename string `json:"previous_filename,omitempty"`
-	Status           string `json:"status"`
+	// The status of the file change (added, modified, deleted, etc.)
-	Additions        int    `json:"additions"`
+	Status string `json:"status"`
-	Deletions        int    `json:"deletions"`
+	// The number of lines added to the file
-	Changes          int    `json:"changes"`
+	Additions int `json:"additions"`
-	HTMLURL          string `json:"html_url,omitempty"`
+	// The number of lines deleted from the file
-	ContentsURL      string `json:"contents_url,omitempty"`
+	Deletions int `json:"deletions"`
-	RawURL           string `json:"raw_url,omitempty"`
+	// 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     string `json:"html_url"`
+	// 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,44 +9,70 @@ import (
 
 // Release represents a repository release
 type Release struct {
-	ID           int64  `json:"id"`
+	// The unique identifier of the release
-	TagName      string `json:"tag_name"`
+	ID int64 `json:"id"`
-	Target       string `json:"target_commitish"`
+	// The name of the git tag associated with the release
-	Title        string `json:"name"`
+	TagName string `json:"tag_name"`
-	Note         string `json:"body"`
+	// The target commitish for the release
-	URL          string `json:"url"`
+	Target string `json:"target_commitish"`
-	HTMLURL      string `json:"html_url"`
+	// The display title of the release
-	TarURL       string `json:"tarball_url"`
+	Title string `json:"name"`
-	ZipURL       string `json:"zipball_url"`
+	// The release notes or description
-	UploadURL    string `json:"upload_url"`
+	Note string `json:"body"`
-	IsDraft      bool   `json:"draft"`
+	// The API URL of the release
-	IsPrerelease bool   `json:"prerelease"`
+	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"`
+	PublishedAt time.Time `json:"published_at"`
-	Publisher   *User         `json:"author"`
+	// The user who published the release
+	Publisher *User `json:"author"`
+	// The files attached to the release
 	Attachments []*Attachment `json:"assets"`
 }
 
 // CreateReleaseOption options when creating a release
 type CreateReleaseOption struct {
 	// required: true
-	TagName      string `json:"tag_name" binding:"Required"`
+	TagName string `json:"tag_name" binding:"Required"`
-	TagMessage   string `json:"tag_message"`
+	// The message for the git tag
-	Target       string `json:"target_commitish"`
+	TagMessage string `json:"tag_message"`
-	Title        string `json:"name"`
+	// The target commitish for the release
-	Note         string `json:"body"`
+	Target string `json:"target_commitish"`
-	IsDraft      bool   `json:"draft"`
+	// The display title of the release
-	IsPrerelease bool   `json:"prerelease"`
+	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 {
-	TagName      string `json:"tag_name"`
+	// The new name of the git tag
-	Target       string `json:"target_commitish"`
+	TagName string `json:"tag_name"`
-	Title        string `json:"name"`
+	// The new target commitish for the release
-	Note         string `json:"body"`
+	Target string `json:"target_commitish"`
-	IsDraft      *bool  `json:"draft"`
+	// The new display title of the release
-	IsPrerelease *bool  `json:"prerelease"`
+	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,16 +9,26 @@ import (
 
 // ActionTask represents a ActionTask
 type ActionTask struct {
-	ID           int64  `json:"id"`
+	// ID is the unique identifier for the action task
-	Name         string `json:"name"`
+	ID int64 `json:"id"`
-	HeadBranch   string `json:"head_branch"`
+	// Name is the name of the workflow
-	HeadSHA      string `json:"head_sha"`
+	Name string `json:"name"`
-	RunNumber    int64  `json:"run_number"`
+	// HeadBranch is the branch that triggered the workflow
-	Event        string `json:"event"`
+	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       string `json:"status"`
+	// Status indicates the current status of the workflow run
-	WorkflowID   string `json:"workflow_id"`
+	Status string `json:"status"`
-	URL          string `json:"url"`
+	// 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"`
 	// swagger:strfmt date-time
@@ -29,8 +39,10 @@ type ActionTask struct {
 
 // ActionTaskResponse returns a ActionTask
 type ActionTaskResponse struct {
-	Entries    []*ActionTask `json:"workflow_runs"`
+	// Entries contains the list of workflow runs
-	TotalCount int64         `json:"total_count"`
+	Entries []*ActionTask `json:"workflow_runs"`
+	// TotalCount is the total number of workflow runs
+	TotalCount int64 `json:"total_count"`
 }
 
 // CreateActionWorkflowDispatch represents the payload for triggering a workflow dispatch event
@@ -45,17 +57,24 @@ type CreateActionWorkflowDispatch struct {
 
 // ActionWorkflow represents a ActionWorkflow
 type ActionWorkflow struct {
-	ID    string `json:"id"`
+	// ID is the unique identifier for the workflow
-	Name  string `json:"name"`
+	ID string `json:"id"`
-	Path  string `json:"path"`
+	// 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       string    `json:"url"`
+	// URL is the API URL for this workflow
-	HTMLURL   string    `json:"html_url"`
+	URL string `json:"url"`
-	BadgeURL  string    `json:"badge_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,22 +9,33 @@ import (
 
 // Branch represents a repository branch
 type Branch struct {
-	Name                          string         `json:"name"`
+	// Name is the branch name
-	Commit                        *PayloadCommit `json:"commit"`
+	Name string `json:"name"`
-	Protected                     bool           `json:"protected"`
+	// Commit contains the latest commit information for this branch
-	RequiredApprovals             int64          `json:"required_approvals"`
+	Commit *PayloadCommit `json:"commit"`
-	EnableStatusCheck             bool           `json:"enable_status_check"`
+	// Protected indicates if the branch is protected
-	StatusCheckContexts           []string       `json:"status_check_contexts"`
+	Protected bool `json:"protected"`
-	UserCanPush                   bool           `json:"user_can_push"`
+	// RequiredApprovals is the number of required approvals for pull requests
-	UserCanMerge                  bool           `json:"user_can_merge"`
+	RequiredApprovals int64 `json:"required_approvals"`
-	EffectiveBranchProtectionName string         `json:"effective_branch_protection_name"`
+	// 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"`
 }
 
 // BranchProtection represents a branch protection for a repository
 type BranchProtection struct {
 	// Deprecated: true
-	BranchName                    string   `json:"branch_name"`
+	BranchName string `json:"branch_name"`
-	RuleName                      string   `json:"rule_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   string `json:"role_name"`
+	// RoleName is the name of the permission role
-	User       *User  `json:"user"`
+	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          string                     `json:"url"`
+	// URL is the API URL for the commit
-	Author       *CommitUser                `json:"author"`
+	URL string `json:"url"`
-	Committer    *CommitUser                `json:"committer"`
+	// Author contains the commit author information
-	Message      string                     `json:"message"`
+	Author *CommitUser `json:"author"`
-	Tree         *CommitMeta                `json:"tree"`
+	// 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     int `json:"total"`
+	// 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    string                 `json:"html_url"`
+	// HTMLURL is the web URL for viewing the commit
-	RepoCommit *RepoCommit            `json:"commit"`
+	HTMLURL string `json:"html_url"`
-	Author     *User                  `json:"author"`
+	// RepoCommit contains the commit information
-	Committer  *User                  `json:"committer"`
+	RepoCommit *RepoCommit `json:"commit"`
-	Parents    []*CommitMeta          `json:"parents"`
+	// Author is the GitHub/Gitea user who authored the commit
-	Files      []*CommitAffectedFiles `json:"files"`
+	Author *User `json:"author"`
-	Stats      *CommitStats           `json:"stats"`
+	// 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   string `json:"status"`
+	// Status indicates how the file was affected (added, modified, deleted)
+	Status string `json:"status"`
 }

modules/structs/repo_file.go

@@ -104,83 +104,117 @@ type ApplyDiffPatchFileOptions struct {
 
 // FileLinksResponse contains the links for a repo's file
 type FileLinksResponse struct {
-	Self    *string `json:"self"`
+	// Self is the API URL for this file
-	GitURL  *string `json:"git"`
+	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 *ContentsResponse   `json:"file_contents,omitempty"`
+	// FileContents contains file information when the path represents a file
-	DirContents  []*ContentsResponse `json:"dir_contents,omitempty"`
+	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  string `json:"sha"`
+	// 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"`
+	LastAuthorDate *time.Time `json:"last_author_date,omitempty"`
-	LastCommitMessage *string    `json:"last_commit_message,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 int64  `json:"size"`
+	// Size is the file size in bytes
+	Size int64 `json:"size"`
 	// `encoding` is populated when `type` is `file`, otherwise null
 	Encoding *string `json:"encoding"`
 	// `content` is populated when `type` is `file`, otherwise null
 	Content *string `json:"content"`
 	// `target` is populated when `type` is `symlink`, otherwise null
-	Target      *string `json:"target"`
+	Target *string `json:"target"`
-	URL         *string `json:"url"`
+	// URL is the API URL for this file or directory
-	HTMLURL     *string `json:"html_url"`
+	URL *string `json:"url"`
-	GitURL      *string `json:"git_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"`
+	SubmoduleGitURL *string `json:"submodule_git_url"`
-	Links           *FileLinksResponse `json:"_links"`
+	// Links contains related URLs for this file or directory
+	Links *FileLinksResponse `json:"_links"`
 
-	LfsOid  *string `json:"lfs_oid,omitempty"`
+	// LfsOid is the Git LFS object ID if this file is stored in LFS
-	LfsSize *int64  `json:"lfs_size,omitempty"`
+	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   string        `json:"html_url"`
+	// HTMLURL is the web URL for viewing this commit
-	Author    *CommitUser   `json:"author"`
+	HTMLURL string `json:"html_url"`
-	Committer *CommitUser   `json:"committer"`
+	// Author is the commit author information
-	Parents   []*CommitMeta `json:"parents"`
+	Author *CommitUser `json:"author"`
-	Message   string        `json:"message"`
+	// Committer is the commit committer information
-	Tree      *CommitMeta   `json:"tree"`
+	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      *ContentsResponse          `json:"content"`
+	// Content contains the file content and metadata
-	Commit       *FileCommitResponse        `json:"commit"`
+	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        []*ContentsResponse        `json:"files"`
+	// Files contains the list of file contents and metadata
-	Commit       *FileCommitResponse        `json:"commit"`
+	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      any                        `json:"content"` // to be set to nil
+	// Content is always null for delete operations
-	Commit       *FileCommitResponse        `json:"commit"`
+	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          int64  `json:"id"`
+	// ID is the unique identifier for the deploy key
-	KeyID       int64  `json:"key_id"`
+	ID int64 `json:"id"`
-	Key         string `json:"key"`
+	// KeyID is the associated public key ID
-	URL         string `json:"url"`
+	KeyID int64 `json:"key_id"`
-	Title       string `json:"title"`
+	// 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    time.Time   `json:"created_at"`
+	// Created is the time when the deploy key was added
-	ReadOnly   bool        `json:"read_only"`
+	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 {
-	Message string  `json:"message"`
+	// The content message of the git note
-	Commit  *Commit `json:"commit"`
+	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 {
-	Ref    string     `json:"ref"`
+	// The name of the Git reference (e.g., refs/heads/main)
-	URL    string     `json:"url"`
+	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"`
-	SHA  string `json:"sha"`
+	// The SHA hash of the Git object
-	URL  string `json:"url"`
+	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 {
-	Name       string      `json:"name"`
+	// The name of the tag
-	Message    string      `json:"message"`
+	Name string `json:"name"`
-	ID         string      `json:"id"`
+	// The message associated with the tag
-	Commit     *CommitMeta `json:"commit"`
+	Message string `json:"message"`
-	ZipballURL string      `json:"zipball_url,omitempty"`
+	// The ID (SHA) of the tag
-	TarballURL string      `json:"tarball_url,omitempty"`
+	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 {
-	Tag          string                     `json:"tag"`
+	// The name of the annotated tag
-	SHA          string                     `json:"sha"`
+	Tag string `json:"tag"`
-	URL          string                     `json:"url"`
+	// The SHA hash of the annotated tag
-	Message      string                     `json:"message"`
+	SHA string `json:"sha"`
-	Tagger       *CommitUser                `json:"tagger"`
+	// The URL to access the annotated tag
-	Object       *AnnotatedTagObject        `json:"object"`
+	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"`
-	URL  string `json:"url"`
+	// The URL to access the tagged object
-	SHA  string `json:"sha"`
+	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"`
-	Target  string `json:"target"`
+	// The target commit SHA or branch name for the tag
+	Target string `json:"target"`
 }
 
 // TagProtection represents a tag protection
 type TagProtection struct {
-	ID                 int64    `json:"id"`
+	// The unique identifier of the tag protection
-	NamePattern        string   `json:"name_pattern"`
+	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"`
-	WhitelistTeams     []string `json:"whitelist_teams"`
+	// 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 {
-	NamePattern        string   `json:"name_pattern"`
+	// 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"`
-	WhitelistTeams     []string `json:"whitelist_teams"`
+	// 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 {
-	NamePattern        *string  `json:"name_pattern"`
+	// 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"`
-	WhitelistTeams     []string `json:"whitelist_teams"`
+	// 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 {
-	ID        int64     `json:"id"`
+	// The unique identifier of the topic
-	Name      string    `json:"topic_name"`
+	ID int64 `json:"id"`
-	RepoCount int       `json:"repo_count"`
+	// The name of the topic
-	Created   time.Time `json:"created"`
+	Name string `json:"topic_name"`
-	Updated   time.Time `json:"updated"`
+	// 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 int64  `json:"size"`
+	// Size is the file size in bytes
-	SHA  string `json:"sha"`
+	Size int64 `json:"size"`
-	URL  string `json:"url"`
+	// 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        string     `json:"sha"`
+	// SHA is the tree object SHA
-	URL        string     `json:"url"`
+	SHA string `json:"sha"`
-	Entries    []GitEntry `json:"tree"`
+	// URL is the API URL for this tree
-	Truncated  bool       `json:"truncated"`
+	URL string `json:"url"`
-	Page       int        `json:"page"`
+	// Entries contains the tree entries (files and directories)
-	TotalCount int        `json:"total_count"`
+	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 {
-	Subscribed    bool      `json:"subscribed"`
+	// Whether the repository is being watched for notifications
-	Ignored       bool      `json:"ignored"`
+	Subscribed bool `json:"subscribed"`
-	Reason        any       `json:"reason"`
+	// Whether notifications for the repository are ignored
-	CreatedAt     time.Time `json:"created_at"`
+	Ignored bool `json:"ignored"`
-	URL           string    `json:"url"`
+	// The reason for the current watch status
-	RepositoryURL string    `json:"repository_url"`
+	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,10 +5,14 @@ package structs
 
 // WikiCommit page commit/revision
 type WikiCommit struct {
-	ID        string      `json:"sha"`
+	// The commit SHA hash
-	Author    *CommitUser `json:"author"`
+	ID string `json:"sha"`
+	// The author of the commit
+	Author *CommitUser `json:"author"`
+	// The committer of the commit
 	Committer *CommitUser `json:"commiter"`
-	Message   string      `json:"message"`
+	// The commit message
+	Message string `json:"message"`
 }
 
 // WikiPage a wiki page
@@ -16,16 +20,23 @@ type WikiPage struct {
 	*WikiPageMetaData
 	// Page content, base64 encoded
 	ContentBase64 string `json:"content_base64"`
-	CommitCount   int64  `json:"commit_count"`
+	// The number of commits that modified this page
-	Sidebar       string `json:"sidebar"`
+	CommitCount int64 `json:"commit_count"`
-	Footer        string `json:"footer"`
+	// 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 {
-	Title      string      `json:"title"`
+	// The title of the wiki page
-	HTMLURL    string      `json:"html_url"`
+	Title string `json:"title"`
-	SubURL     string      `json:"sub_url"`
+	// 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"`
-	Count       int64         `json:"count"`
+	// 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      bool `json:"mirrors_disabled"`
+	// MirrorsDisabled indicates if repository mirroring is disabled
-	HTTPGitDisabled      bool `json:"http_git_disabled"`
+	MirrorsDisabled bool `json:"mirrors_disabled"`
-	MigrationsDisabled   bool `json:"migrations_disabled"`
+	// HTTPGitDisabled indicates if HTTP Git operations are disabled
-	StarsDisabled        bool `json:"stars_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          bool `json:"lfs_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     string   `json:"default_theme"`
+	// 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     []string `json:"custom_emojis"`
+	// CustomEmojis contains the list of custom emojis
+	CustomEmojis []string `json:"custom_emojis"`
 }
 
 // GeneralAPISettings contains global api settings exposed by it
 type GeneralAPISettings struct {
-	MaxResponseItems       int   `json:"max_response_items"`
+	// MaxResponseItems is the maximum number of items returned in API responses
-	DefaultPagingNum       int   `json:"default_paging_num"`
+	MaxResponseItems int `json:"max_response_items"`
-	DefaultGitTreesPerPage int   `json:"default_git_trees_per_page"`
+	// DefaultPagingNum is the default number of items per page
-	DefaultMaxBlobSize     int64 `json:"default_max_blob_size"`
+	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      bool   `json:"enabled"`
+	// 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      int64  `json:"max_size"`
+	// MaxSize is the maximum size for individual attachments
-	MaxFiles     int    `json:"max_files"`
+	MaxSize int64 `json:"max_size"`
+	// MaxFiles is the maximum number of files per attachment
+	MaxFiles int `json:"max_files"`
 }

modules/structs/status.go

@@ -11,13 +11,20 @@ import (
 
 // CommitStatus holds a single status of a single Commit
 type CommitStatus struct {
-	ID          int64                          `json:"id"`
+	// ID is the unique identifier for the commit status
-	State       commitstatus.CommitStatusState `json:"status"`
+	ID int64 `json:"id"`
-	TargetURL   string                         `json:"target_url"`
+	// State represents the status state (pending, success, error, failure)
-	Description string                         `json:"description"`
+	State commitstatus.CommitStatusState `json:"status"`
-	URL         string                         `json:"url"`
+	// TargetURL is the URL to link to for more details
-	Context     string                         `json:"context"`
+	TargetURL string `json:"target_url"`
-	Creator     *User                          `json:"creator"`
+	// 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"`
 	// swagger:strfmt date-time
@@ -26,19 +33,30 @@ type CommitStatus struct {
 
 // CombinedStatus holds the combined state of several statuses for a single commit
 type CombinedStatus struct {
-	State      commitstatus.CommitStatusState `json:"state"`
+	// State is the overall combined status state
-	SHA        string                         `json:"sha"`
+	State commitstatus.CommitStatusState `json:"state"`
-	TotalCount int                            `json:"total_count"`
+	// SHA is the commit SHA this status applies to
-	Statuses   []*CommitStatus                `json:"statuses"`
+	SHA string `json:"sha"`
-	Repository *Repository                    `json:"repository"`
+	// TotalCount is the total number of statuses
-	CommitURL  string                         `json:"commit_url"`
+	TotalCount int `json:"total_count"`
-	URL        string                         `json:"url"`
+	// 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       commitstatus.CommitStatusState `json:"state"`
+	// State represents the status state to set (pending, success, error, failure)
-	TargetURL   string                         `json:"target_url"`
+	State commitstatus.CommitStatusState `json:"state"`
-	Description string                         `json:"description"`
+	// TargetURL is the URL to link to for more details
-	Context     string                         `json:"context"`
+	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,13 +11,20 @@ import (
 // AccessToken represents an API access token.
 // swagger:response AccessToken
 type AccessToken struct {
-	ID             int64     `json:"id"`
+	// The unique identifier of the access token
-	Name           string    `json:"name"`
+	ID int64 `json:"id"`
-	Token          string    `json:"sha1"`
+	// The name of the access token
-	TokenLastEight string    `json:"token_last_eight"`
+	Name string `json:"name"`
-	Scopes         []string  `json:"scopes"`
+	// The SHA1 hash of the access token
-	Created        time.Time `json:"created_at"`
+	Token string `json:"sha1"`
-	Updated        time.Time `json:"last_used_at"`
+	// 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"`
 }
 
 // AccessTokenList represents a list of API access token.
@@ -35,23 +42,35 @@ type CreateAccessTokenOption struct {
 
 // CreateOAuth2ApplicationOptions holds options to create an oauth2 application
 type CreateOAuth2ApplicationOptions struct {
-	Name                       string   `json:"name" binding:"Required"`
+	// The name of the OAuth2 application
-	ConfidentialClient         bool     `json:"confidential_client"`
+	Name string `json:"name" binding:"Required"`
-	SkipSecondaryAuthorization bool     `json:"skip_secondary_authorization"`
+	// Whether the client is confidential
-	RedirectURIs               []string `json:"redirect_uris" binding:"Required"`
+	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 {
-	ID                         int64     `json:"id"`
+	// The unique identifier of the OAuth2 application
-	Name                       string    `json:"name"`
+	ID int64 `json:"id"`
-	ClientID                   string    `json:"client_id"`
+	// The name of the OAuth2 application
-	ClientSecret               string    `json:"client_secret"`
+	Name string `json:"name"`
-	ConfidentialClient         bool      `json:"confidential_client"`
+	// The client ID of the OAuth2 application
-	SkipSecondaryAuthorization bool      `json:"skip_secondary_authorization"`
+	ClientID string `json:"client_id"`
-	RedirectURIs               []string  `json:"redirect_uris"`
+	// The client secret of the OAuth2 application
-	Created                    time.Time `json:"created"`
+	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"`
 }
 
 // OAuth2ApplicationList represents a list of OAuth2 applications.

modules/structs/user_email.go

@@ -7,10 +7,14 @@ package structs
 // Email an email address belonging to a user
 type Email struct {
 	// swagger:strfmt email
-	Email    string `json:"email"`
+	// The email address
-	Verified bool   `json:"verified"`
+	Email string `json:"email"`
-	Primary  bool   `json:"primary"`
+	// Whether the email address has been verified
-	UserID   int64  `json:"user_id"`
+	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,28 +9,43 @@ import (
 
 // GPGKey a user GPG key to sign commit and tag in repository
 type GPGKey struct {
-	ID                int64          `json:"id"`
+	// The unique identifier of the GPG key
-	PrimaryKeyID      string         `json:"primary_key_id"`
+	ID int64 `json:"id"`
-	KeyID             string         `json:"key_id"`
+	// The primary key ID of the GPG key
-	PublicKey         string         `json:"public_key"`
+	PrimaryKeyID string `json:"primary_key_id"`
-	Emails            []*GPGKeyEmail `json:"emails"`
+	// The key ID of the GPG key
-	SubsKey           []*GPGKey      `json:"subkeys"`
+	KeyID string `json:"key_id"`
-	CanSign           bool           `json:"can_sign"`
+	// The public key content in armored format
-	CanEncryptComms   bool           `json:"can_encrypt_comms"`
+	PublicKey string `json:"public_key"`
-	CanEncryptStorage bool           `json:"can_encrypt_storage"`
+	// List of email addresses associated with this GPG key
-	CanCertify        bool           `json:"can_certify"`
+	Emails []*GPGKeyEmail `json:"emails"`
-	Verified          bool           `json:"verified"`
+	// 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 {
-	Email    string `json:"email"`
+	// The email address associated with the GPG key
-	Verified bool   `json:"verified"`
+	Email string `json:"email"`
+	// Whether the email address has been verified
+	Verified bool `json:"verified"`
 }
 
 // CreateGPGKeyOption options create user GPG key
@@ -40,7 +55,8 @@ type CreateGPGKeyOption struct {
 	// required: true
 	// unique: true
 	ArmoredKey string `json:"armored_public_key" binding:"Required"`
-	Signature  string `json:"armored_signature,omitempty"`
+	// An optional armored signature for the GPG key
+	Signature string `json:"armored_signature,omitempty"`
 }
 
 // VerifyGPGKeyOption options verifies user GPG key
@@ -48,6 +64,8 @@ type VerifyGPGKeyOption struct {
 	// An Signature for a GPG key token
 	//
 	// required: true
-	KeyID     string `json:"key_id" binding:"Required"`
+	// 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          int64  `json:"id"`
+	// ID is the unique identifier for the public key
-	Key         string `json:"key"`
+	ID int64 `json:"id"`
-	URL         string `json:"url,omitempty"`
+	// Key contains the actual SSH public key content
-	Title       string `json:"title,omitempty"`
+	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  time.Time `json:"created_at"`
+	// Created is the time when the key was added
-	Updated  time.Time `json:"last_used_at"`
+	Created time.Time `json:"created_at"`
-	Owner    *User     `json:"user,omitempty"`
+	// Updated is the time when the key was last used
-	ReadOnly bool      `json:"read_only,omitempty"`
+	Updated time.Time `json:"last_used_at"`
-	KeyType  string    `json:"key_type,omitempty"`
+	// 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"`
 }