Clarify owner and parent field descriptions in response/request models

Author: AlexMaryW

modules/structs/issue.go

@@ -35,8 +35,9 @@ type PullRequestMeta struct {
 
 // RepositoryMeta basic repository information
 type RepositoryMeta struct {
-	ID       int64  `json:"id"`
-	Name     string `json:"name"`
+	ID   int64  `json:"id"`
+	Name string `json:"name"`
+	// username of the user or organization owning the repository
 	Owner    string `json:"owner"`
 	FullName string `json:"full_name"`
 }
@@ -262,7 +263,8 @@ func (it IssueTemplate) Type() IssueTemplateType {
 // IssueMeta basic issue information
 // swagger:model
 type IssueMeta struct {
-	Index int64  `json:"index"`
+	Index int64 `json:"index"`
+	// username of the user or organization owning the issue
 	Owner string `json:"owner"`
 	Name  string `json:"repo"`
 }

modules/structs/issue_stopwatch.go

@@ -10,13 +10,14 @@ import (
 // StopWatch represent a running stopwatch
 type StopWatch struct {
 	// swagger:strfmt date-time
-	Created       time.Time `json:"created"`
-	Seconds       int64     `json:"seconds"`
-	Duration      string    `json:"duration"`
-	IssueIndex    int64     `json:"issue_index"`
-	IssueTitle    string    `json:"issue_title"`
-	RepoOwnerName string    `json:"repo_owner_name"`
-	RepoName      string    `json:"repo_name"`
+	Created    time.Time `json:"created"`
+	Seconds    int64     `json:"seconds"`
+	Duration   string    `json:"duration"`
+	IssueIndex int64     `json:"issue_index"`
+	IssueTitle string    `json:"issue_title"`
+	// username of the user or organization owning the repository
+	RepoOwnerName string `json:"repo_owner_name"`
+	RepoName      string `json:"repo_name"`
 }
 
 // StopWatches represent a list of stopwatches

modules/structs/package.go

@@ -9,7 +9,8 @@ import (
 
 // Package represents a package
 type Package struct {
-	ID         int64       `json:"id"`
+	ID int64 `json:"id"`
+	// user or organization owning the package
 	Owner      *User       `json:"owner"`
 	Repository *Repository `json:"repository"`
 	Creator    *User       `json:"creator"`

modules/structs/repo.go

@@ -48,15 +48,17 @@ type ExternalWiki struct {
 
 // Repository represents a repository
 type Repository struct {
-	ID            int64       `json:"id"`
-	Owner         *User       `json:"owner"`
-	Name          string      `json:"name"`
-	FullName      string      `json:"full_name"`
-	Description   string      `json:"description"`
-	Empty         bool        `json:"empty"`
-	Private       bool        `json:"private"`
-	Fork          bool        `json:"fork"`
-	Template      bool        `json:"template"`
+	ID int64 `json:"id"`
+	// user or organization owning the repository
+	Owner       *User  `json:"owner"`
+	Name        string `json:"name"`
+	FullName    string `json:"full_name"`
+	Description string `json:"description"`
+	Empty       bool   `json:"empty"`
+	Private     bool   `json:"private"`
+	Fork        bool   `json:"fork"`
+	Template    bool   `json:"template"`
+	// the original repository if the repository in the parameter is a fork; else empty
 	Parent        *Repository `json:"parent,omitempty"`
 	Mirror        bool        `json:"mirror"`
 	Size          int         `json:"size"`
@@ -228,12 +230,10 @@ type EditRepoOption struct {
 // GenerateRepoOption options when creating repository using a template
 // swagger:model
 type GenerateRepoOption struct {
-	// The organization or person who will own the new repository
+	// username of the user or organization who will own the repository
 	//
 	// required: true
 	Owner string `json:"owner"`
-	// Name of the repository to create
-	//
 	// required: true
 	// unique: true
 	Name string `json:"name" binding:"Required;AlphaDashDot;MaxSize(100)"`
@@ -293,6 +293,7 @@ type UpdateBranchRepoOption struct {
 // TransferRepoOption options when transfer a repository's ownership
 // swagger:model
 type TransferRepoOption struct {
+	// username of the user or organization who will own the repository
 	// required: true
 	NewOwner string `json:"new_owner"`
 	// ID of the team or teams to add to the repository. Teams can only be added to organization-owned repositories.
@@ -354,7 +355,7 @@ type MigrateRepoOptions struct {
 	CloneAddr string `json:"clone_addr" binding:"Required"`
 	// deprecated (only for backwards compatibility)
 	RepoOwnerID int64 `json:"uid"`
-	// Name of User or Organisation who will own Repo after migration
+	// username of the user or organization who will own the repository after migration
 	RepoOwner string `json:"repo_owner"`
 	// required: true
 	RepoName string `json:"repo_name" binding:"Required;AlphaDashDot;MaxSize(100)"`

modules/structs/user_key.go

@@ -15,9 +15,10 @@ type PublicKey struct {
 	Title       string `json:"title,omitempty"`
 	Fingerprint string `json:"fingerprint,omitempty"`
 	// swagger:strfmt date-time
-	Created  time.Time `json:"created_at"`
-	Updated  time.Time `json:"last_used_at"`
-	Owner    *User     `json:"user,omitempty"`
-	ReadOnly bool      `json:"read_only,omitempty"`
-	KeyType  string    `json:"key_type,omitempty"`
+	Created time.Time `json:"created_at"`
+	Updated time.Time `json:"last_used_at"`
+	// user or organization owning the key
+	Owner    *User  `json:"user,omitempty"`
+	ReadOnly bool   `json:"read_only,omitempty"`
+	KeyType  string `json:"key_type,omitempty"`
 }