diff --git a/github/activity_events.go b/github/activity_events.go index b12baa99e67..597f7992092 100644 --- a/github/activity_events.go +++ b/github/activity_events.go @@ -143,6 +143,7 @@ func (s *ActivityService) ListEventsForOrganization(ctx context.Context, org str // true, only public events will be returned. // // GitHub API docs: https://docs.github.com/rest/activity/events#list-events-for-the-authenticated-user +// // GitHub API docs: https://docs.github.com/rest/activity/events#list-public-events-for-a-user // //meta:operation GET /users/{username}/events @@ -177,6 +178,7 @@ func (s *ActivityService) ListEventsPerformedByUser(ctx context.Context, user st // true, only public events will be returned. // // GitHub API docs: https://docs.github.com/rest/activity/events#list-events-received-by-the-authenticated-user +// // GitHub API docs: https://docs.github.com/rest/activity/events#list-public-events-received-by-a-user // //meta:operation GET /users/{username}/received_events diff --git a/github/activity_star.go b/github/activity_star.go index bc68dfef2dd..d9383e434ed 100644 --- a/github/activity_star.go +++ b/github/activity_star.go @@ -69,6 +69,7 @@ type ActivityListStarredOptions struct { // will list the starred repositories for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/activity/starring#list-repositories-starred-by-a-user +// // GitHub API docs: https://docs.github.com/rest/activity/starring#list-repositories-starred-by-the-authenticated-user // //meta:operation GET /user/starred diff --git a/github/activity_watching.go b/github/activity_watching.go index 61429177862..8106d799cf1 100644 --- a/github/activity_watching.go +++ b/github/activity_watching.go @@ -55,6 +55,7 @@ func (s *ActivityService) ListWatchers(ctx context.Context, owner, repo string, // the empty string will fetch watched repos for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/activity/watching#list-repositories-watched-by-a-user +// // GitHub API docs: https://docs.github.com/rest/activity/watching#list-repositories-watched-by-the-authenticated-user // //meta:operation GET /user/subscriptions diff --git a/github/apps.go b/github/apps.go index e1bede64717..fe36b9584dc 100644 --- a/github/apps.go +++ b/github/apps.go @@ -215,6 +215,7 @@ func (i Installation) String() string { // (e.g., https://github.com/settings/apps/:app_slug). // // GitHub API docs: https://docs.github.com/rest/apps/apps#get-an-app +// // GitHub API docs: https://docs.github.com/rest/apps/apps#get-the-authenticated-app // //meta:operation GET /app diff --git a/github/apps_marketplace.go b/github/apps_marketplace.go index 976775a79a0..33382378e2e 100644 --- a/github/apps_marketplace.go +++ b/github/apps_marketplace.go @@ -90,6 +90,7 @@ type MarketplacePurchaseAccount struct { // ListPlans lists all plans for your Marketplace listing. // // GitHub API docs: https://docs.github.com/rest/apps/marketplace#list-plans +// // GitHub API docs: https://docs.github.com/rest/apps/marketplace#list-plans-stubbed // //meta:operation GET /marketplace_listing/plans @@ -118,6 +119,7 @@ func (s *MarketplaceService) ListPlans(ctx context.Context, opts *ListOptions) ( // ListPlanAccountsForPlan lists all GitHub accounts (user or organization) on a specific plan. // // GitHub API docs: https://docs.github.com/rest/apps/marketplace#list-accounts-for-a-plan +// // GitHub API docs: https://docs.github.com/rest/apps/marketplace#list-accounts-for-a-plan-stubbed // //meta:operation GET /marketplace_listing/plans/{plan_id}/accounts @@ -146,6 +148,7 @@ func (s *MarketplaceService) ListPlanAccountsForPlan(ctx context.Context, planID // GetPlanAccountForAccount get GitHub account (user or organization) associated with an account. // // GitHub API docs: https://docs.github.com/rest/apps/marketplace#get-a-subscription-plan-for-an-account +// // GitHub API docs: https://docs.github.com/rest/apps/marketplace#get-a-subscription-plan-for-an-account-stubbed // //meta:operation GET /marketplace_listing/accounts/{account_id} @@ -170,6 +173,7 @@ func (s *MarketplaceService) GetPlanAccountForAccount(ctx context.Context, accou // ListMarketplacePurchasesForUser lists all GitHub marketplace purchases made by a user. // // GitHub API docs: https://docs.github.com/rest/apps/marketplace#list-subscriptions-for-the-authenticated-user +// // GitHub API docs: https://docs.github.com/rest/apps/marketplace#list-subscriptions-for-the-authenticated-user-stubbed // //meta:operation GET /user/marketplace_purchases diff --git a/github/gists.go b/github/gists.go index ee4314b986e..8b5dd47d8ec 100644 --- a/github/gists.go +++ b/github/gists.go @@ -97,6 +97,7 @@ type GistListOptions struct { // user. // // GitHub API docs: https://docs.github.com/rest/gists/gists#list-gists-for-a-user +// // GitHub API docs: https://docs.github.com/rest/gists/gists#list-gists-for-the-authenticated-user // //meta:operation GET /gists diff --git a/github/issues.go b/github/issues.go index d19987f26bf..861c3fa5f90 100644 --- a/github/issues.go +++ b/github/issues.go @@ -160,6 +160,7 @@ type IssueType struct { // repositories. // // GitHub API docs: https://docs.github.com/rest/issues/issues#list-issues-assigned-to-the-authenticated-user +// // GitHub API docs: https://docs.github.com/rest/issues/issues#list-user-account-issues-assigned-to-the-authenticated-user // //meta:operation GET /issues diff --git a/github/issues_comments.go b/github/issues_comments.go index 35069400de8..ef5314b188d 100644 --- a/github/issues_comments.go +++ b/github/issues_comments.go @@ -55,6 +55,7 @@ type IssueListCommentsOptions struct { // number of 0 will return all comments on all issues for the repository. // // GitHub API docs: https://docs.github.com/rest/issues/comments#list-issue-comments +// // GitHub API docs: https://docs.github.com/rest/issues/comments#list-issue-comments-for-a-repository // //meta:operation GET /repos/{owner}/{repo}/issues/comments diff --git a/github/orgs.go b/github/orgs.go index c1f7bf0d028..185d0393039 100644 --- a/github/orgs.go +++ b/github/orgs.go @@ -194,6 +194,7 @@ func (s *OrganizationsService) ListAll(ctx context.Context, opts *OrganizationsL // organizations for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/orgs/orgs#list-organizations-for-a-user +// // GitHub API docs: https://docs.github.com/rest/orgs/orgs#list-organizations-for-the-authenticated-user // //meta:operation GET /user/orgs diff --git a/github/orgs_members.go b/github/orgs_members.go index 002811c6eac..837a8f44677 100644 --- a/github/orgs_members.go +++ b/github/orgs_members.go @@ -72,6 +72,7 @@ type ListMembersOptions struct { // public members; otherwise, it will only return public members. // // GitHub API docs: https://docs.github.com/rest/orgs/members#list-organization-members +// // GitHub API docs: https://docs.github.com/rest/orgs/members#list-public-organization-members // //meta:operation GET /orgs/{org}/members @@ -237,6 +238,7 @@ func (s *OrganizationsService) ListOrgMemberships(ctx context.Context, opts *Lis // authenticated user. // // GitHub API docs: https://docs.github.com/rest/orgs/members#get-an-organization-membership-for-the-authenticated-user +// // GitHub API docs: https://docs.github.com/rest/orgs/members#get-organization-membership-for-a-user // //meta:operation GET /orgs/{org}/memberships/{username} @@ -268,6 +270,7 @@ func (s *OrganizationsService) GetOrgMembership(ctx context.Context, user, org s // authenticated user. // // GitHub API docs: https://docs.github.com/rest/orgs/members#set-organization-membership-for-a-user +// // GitHub API docs: https://docs.github.com/rest/orgs/members#update-an-organization-membership-for-the-authenticated-user // //meta:operation PUT /orgs/{org}/memberships/{username} diff --git a/github/pulls_comments.go b/github/pulls_comments.go index 03b3c1d2057..4d601730b48 100644 --- a/github/pulls_comments.go +++ b/github/pulls_comments.go @@ -73,6 +73,7 @@ type PullRequestListCommentsOptions struct { // the repository. // // GitHub API docs: https://docs.github.com/rest/pulls/comments#list-review-comments-in-a-repository +// // GitHub API docs: https://docs.github.com/rest/pulls/comments#list-review-comments-on-a-pull-request // //meta:operation GET /repos/{owner}/{repo}/pulls/comments diff --git a/github/repos.go b/github/repos.go index 0119a01b5c4..24444273edc 100644 --- a/github/repos.go +++ b/github/repos.go @@ -263,6 +263,7 @@ type SecretScanningValidityChecks struct { // Deprecated: Use RepositoriesService.ListByUser or RepositoriesService.ListByAuthenticatedUser instead. // // GitHub API docs: https://docs.github.com/rest/repos/repos#list-repositories-for-a-user +// // GitHub API docs: https://docs.github.com/rest/repos/repos#list-repositories-for-the-authenticated-user // //meta:operation GET /user/repos @@ -530,6 +531,7 @@ type createRepoRequest struct { // exponential back-off to verify repository's creation. // // GitHub API docs: https://docs.github.com/rest/repos/repos#create-a-repository-for-the-authenticated-user +// // GitHub API docs: https://docs.github.com/rest/repos/repos#create-an-organization-repository // //meta:operation POST /orgs/{org}/repos diff --git a/github/repos_contents.go b/github/repos_contents.go index 2378cd2330e..6090c8b9f92 100644 --- a/github/repos_contents.go +++ b/github/repos_contents.go @@ -353,6 +353,7 @@ const ( // or github.Zipball constant. // // GitHub API docs: https://docs.github.com/rest/repos/contents#download-a-repository-archive-tar +// // GitHub API docs: https://docs.github.com/rest/repos/contents#download-a-repository-archive-zip // //meta:operation GET /repos/{owner}/{repo}/tarball/{ref} diff --git a/github/users.go b/github/users.go index 87dcc9a44d3..b3bd3b09b07 100644 --- a/github/users.go +++ b/github/users.go @@ -88,6 +88,7 @@ func (u User) String() string { // user. // // GitHub API docs: https://docs.github.com/rest/users/users#get-a-user +// // GitHub API docs: https://docs.github.com/rest/users/users#get-the-authenticated-user // //meta:operation GET /user diff --git a/github/users_followers.go b/github/users_followers.go index ec6f531eaa4..6833d8df646 100644 --- a/github/users_followers.go +++ b/github/users_followers.go @@ -14,6 +14,7 @@ import ( // fetch followers for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/users/followers#list-followers-of-a-user +// // GitHub API docs: https://docs.github.com/rest/users/followers#list-followers-of-the-authenticated-user // //meta:operation GET /user/followers @@ -48,6 +49,7 @@ func (s *UsersService) ListFollowers(ctx context.Context, user string, opts *Lis // string will list people the authenticated user is following. // // GitHub API docs: https://docs.github.com/rest/users/followers#list-the-people-a-user-follows +// // GitHub API docs: https://docs.github.com/rest/users/followers#list-the-people-the-authenticated-user-follows // //meta:operation GET /user/following @@ -82,6 +84,7 @@ func (s *UsersService) ListFollowing(ctx context.Context, user string, opts *Lis // string for "user" will check if the authenticated user is following "target". // // GitHub API docs: https://docs.github.com/rest/users/followers#check-if-a-person-is-followed-by-the-authenticated-user +// // GitHub API docs: https://docs.github.com/rest/users/followers#check-if-a-user-follows-another-user // //meta:operation GET /user/following/{username} diff --git a/github/users_gpg_keys.go b/github/users_gpg_keys.go index 2f296a1ef62..d33564cab7c 100644 --- a/github/users_gpg_keys.go +++ b/github/users_gpg_keys.go @@ -45,6 +45,7 @@ type GPGEmail struct { // via Basic Auth or via OAuth with at least read:gpg_key scope. // // GitHub API docs: https://docs.github.com/rest/users/gpg-keys#list-gpg-keys-for-a-user +// // GitHub API docs: https://docs.github.com/rest/users/gpg-keys#list-gpg-keys-for-the-authenticated-user // //meta:operation GET /user/gpg_keys diff --git a/github/users_keys.go b/github/users_keys.go index 4d42986ed2b..350a684b797 100644 --- a/github/users_keys.go +++ b/github/users_keys.go @@ -31,6 +31,7 @@ func (k Key) String() string { // string will fetch keys for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/users/keys#list-public-keys-for-a-user +// // GitHub API docs: https://docs.github.com/rest/users/keys#list-public-ssh-keys-for-the-authenticated-user // //meta:operation GET /user/keys diff --git a/github/users_packages.go b/github/users_packages.go index b813dd9d14f..fa6cd9157c1 100644 --- a/github/users_packages.go +++ b/github/users_packages.go @@ -15,6 +15,7 @@ import ( // list packages for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/packages/packages#list-packages-for-a-user +// // GitHub API docs: https://docs.github.com/rest/packages/packages#list-packages-for-the-authenticated-users-namespace // //meta:operation GET /user/packages @@ -49,6 +50,7 @@ func (s *UsersService) ListPackages(ctx context.Context, user string, opts *Pack // get the package for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/packages/packages#get-a-package-for-a-user +// // GitHub API docs: https://docs.github.com/rest/packages/packages#get-a-package-for-the-authenticated-user // //meta:operation GET /user/packages/{package_type}/{package_name} @@ -79,6 +81,7 @@ func (s *UsersService) GetPackage(ctx context.Context, user, packageType, packag // delete the package for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/packages/packages#delete-a-package-for-a-user +// // GitHub API docs: https://docs.github.com/rest/packages/packages#delete-a-package-for-the-authenticated-user // //meta:operation DELETE /user/packages/{package_type}/{package_name} @@ -103,6 +106,7 @@ func (s *UsersService) DeletePackage(ctx context.Context, user, packageType, pac // restore the package for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/packages/packages#restore-a-package-for-a-user +// // GitHub API docs: https://docs.github.com/rest/packages/packages#restore-a-package-for-the-authenticated-user // //meta:operation POST /user/packages/{package_type}/{package_name}/restore @@ -127,6 +131,7 @@ func (s *UsersService) RestorePackage(ctx context.Context, user, packageType, pa // get versions for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/packages/packages#list-package-versions-for-a-package-owned-by-a-user +// // GitHub API docs: https://docs.github.com/rest/packages/packages#list-package-versions-for-a-package-owned-by-the-authenticated-user // //meta:operation GET /user/packages/{package_type}/{package_name}/versions @@ -161,6 +166,7 @@ func (s *UsersService) PackageGetAllVersions(ctx context.Context, user, packageT // get the version for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/packages/packages#get-a-package-version-for-a-user +// // GitHub API docs: https://docs.github.com/rest/packages/packages#get-a-package-version-for-the-authenticated-user // //meta:operation GET /user/packages/{package_type}/{package_name}/versions/{package_version_id} @@ -191,6 +197,7 @@ func (s *UsersService) PackageGetVersion(ctx context.Context, user, packageType, // delete the version for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/packages/packages#delete-a-package-version-for-the-authenticated-user +// // GitHub API docs: https://docs.github.com/rest/packages/packages#delete-package-version-for-a-user // //meta:operation DELETE /user/packages/{package_type}/{package_name}/versions/{package_version_id} @@ -215,6 +222,7 @@ func (s *UsersService) PackageDeleteVersion(ctx context.Context, user, packageTy // restore the version for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/packages/packages#restore-a-package-version-for-the-authenticated-user +// // GitHub API docs: https://docs.github.com/rest/packages/packages#restore-package-version-for-a-user // //meta:operation POST /user/packages/{package_type}/{package_name}/versions/{package_version_id}/restore diff --git a/github/users_ssh_signing_keys.go b/github/users_ssh_signing_keys.go index fcc930be628..968401f028c 100644 --- a/github/users_ssh_signing_keys.go +++ b/github/users_ssh_signing_keys.go @@ -26,6 +26,7 @@ func (k SSHSigningKey) String() string { // username string will fetch SSH signing keys for the authenticated user. // // GitHub API docs: https://docs.github.com/rest/users/ssh-signing-keys#list-ssh-signing-keys-for-a-user +// // GitHub API docs: https://docs.github.com/rest/users/ssh-signing-keys#list-ssh-signing-keys-for-the-authenticated-user // //meta:operation GET /user/ssh_signing_keys diff --git a/tools/metadata/metadata.go b/tools/metadata/metadata.go index 6391a6ffb83..1050e598e61 100644 --- a/tools/metadata/metadata.go +++ b/tools/metadata/metadata.go @@ -333,13 +333,17 @@ func updateDocsVisitor(opsFile *operationsFile) nodeVisitor { } sort.Strings(docLinks) - for _, dl := range docLinks { + for i, dl := range docLinks { group.List = append( group.List, &ast.Comment{ Text: "// GitHub API docs: " + cleanURLPath(dl), }, ) + if i < len(docLinks)-1 { + // add empty line between doc links + group.List = append(group.List, &ast.Comment{Text: "//"}) + } } _, methodName, _ := strings.Cut(serviceMethod, ".") for _, opName := range undocumentedOps { diff --git a/tools/metadata/testdata/golden/TestUpdateGo/valid/github/a.go b/tools/metadata/testdata/golden/TestUpdateGo/valid/github/a.go index 571c1eb2da9..310fc4b9532 100644 --- a/tools/metadata/testdata/golden/TestUpdateGo/valid/github/a.go +++ b/tools/metadata/testdata/golden/TestUpdateGo/valid/github/a.go @@ -28,6 +28,16 @@ func (s *AService) OutdatedLinks() {} //meta:operation GET /a/{a_id} func (s *AService) Uncommented() {} +// Get gets a user. +// +// GitHub API docs: https://docs.github.com/rest/users/users#get-a-user +// +// GitHub API docs: https://docs.github.com/rest/users/users#get-the-authenticated-user +// +//meta:operation GET /user +//meta:operation GET /users/{username} +func (s *AService) Get(user string) {} + func (s *AService) unexported() {} func NotAMethod() {} diff --git a/tools/metadata/testdata/update-go/valid/github/a.go b/tools/metadata/testdata/update-go/valid/github/a.go index 245e2ba1df1..63af01975b0 100644 --- a/tools/metadata/testdata/update-go/valid/github/a.go +++ b/tools/metadata/testdata/update-go/valid/github/a.go @@ -24,6 +24,12 @@ func (s *AService) OutdatedLinks() {} //meta:operation GET /a/{a_id} func (s *AService) Uncommented() {} +// Get gets a user. +// +//meta:operation GET /user +//meta:operation GET /users/{username} +func (s *AService) Get(user string) {} + func (s *AService) unexported() {} func NotAMethod() {} diff --git a/tools/metadata/testdata/update-go/valid/openapi_operations.yaml b/tools/metadata/testdata/update-go/valid/openapi_operations.yaml index ed401c0d283..dfa8af18a47 100644 --- a/tools/metadata/testdata/update-go/valid/openapi_operations.yaml +++ b/tools/metadata/testdata/update-go/valid/openapi_operations.yaml @@ -6,6 +6,10 @@ openapi_operations: - name: GET /a/{a_id} documentation_url: https://docs.github.com/rest/a/a#get-a - name: GET /undocumented/{undocumented_id} + - name: GET /user + documentation_url: https://docs.github.com/rest/users/users#get-a-user + - name: GET /users/{username} + documentation_url: https://docs.github.com/rest/users/users#get-the-authenticated-user operation_overrides: - name: GET /a/{a_id} documentation_url: https://docs.github.com/rest/a/a#overridden-get-a