improve comments

api/queries_issue.go

@@ -257,7 +257,6 @@ func IssueList(client *Client, repo ghrepo.Interface, state string, labels []str
 
 		for i := range milestones {
 			if strings.EqualFold(milestones[i].Title, milestoneString) {
-				// The query for milestones requires the use of the milestone's database ID (see #1441)
 				id, err := milestoneNodeIdToDatabaseId(milestones[i].ID)
 				if err != nil {
 					return nil, err
@@ -439,18 +438,18 @@ func IssueReopen(client *Client, repo ghrepo.Interface, issue Issue) error {
 }
 
 // milestoneNodeIdToDatabaseId extracts the REST Database ID from the GraphQL Node ID
-func milestoneNodeIdToDatabaseId(id string) (string, error) {
-	// The node id is base64 obfuscated
-	decoded, err := base64.StdEncoding.DecodeString(id)
+// This conversion is necessary since the GraphQL API requires the use of the milestone's database ID
+// for querying the related issues.
+func milestoneNodeIdToDatabaseId(nodeId string) (string, error) {
+	// The Node ID is Base64 obfuscated, with an underlying pattern:
+	// "09:Milestone12345", where "12345" is the database ID
+	decoded, err := base64.StdEncoding.DecodeString(nodeId)
 	if err != nil {
 		return "", err
 	}
-
-	// The decoded node ID has a pattern like '09:Milestone12345'
 	splitted := strings.Split(string(decoded), "Milestone")
 	if len(splitted) != 2 {
 		return "", fmt.Errorf("couldn't get database id from node id")
 	}
-
 	return splitted[1], nil
 }

command/issue.go

@@ -61,7 +61,6 @@ var issueCmd = &cobra.Command{
 	$ gh issue list
 	$ gh issue create --label bug
 	$ gh issue view --web
-	$ gh issue list --milestone 'MVP'
 	`),
 	Annotations: map[string]string{
 		"IsCore": "true",
@@ -89,6 +88,7 @@ var issueListCmd = &cobra.Command{
 	$ gh issue list -l "help wanted"
 	$ gh issue list -A monalisa
 	$ gh issue list --web
+	$ gh issue list --milestone 'MVP'
 	`),
 	Args: cmdutil.NoArgsQuoteReminder,
 	RunE: issueList,