Enhance gh search commands' help documentation to clarify use of -- argument interpretation delimiter #10480

Overview

#10467 demonstrates gh search scenarios where users run into problems with argument-based search queries. Though gh search prs has an example highlighting the use of -- argument interpreter delimiter, it requires users to make a few intuited leaps to recognize that is a solution to their problem.

This issue is aimed at improving the following gh commands' documentation to highlight the -- argument interpreter delimiter within the long description and/or examples to aid users:

• gh search code
• gh search commits
• gh search issues
• gh search prs
• gh search repos

Some commands like gh search prs has examples like the following that show -- being used but don't really explain it in the long description or the example comment:

# search pull requests without label "bug"
$ gh search prs -- -label:bug

References

• POSIX.1-2024 > 12.2 Utility Conventions

  Guideline 10:
  The first -- argument that is not an option-argument should be accepted as a delimiter indicating the end of options. Any following arguments should be treated as operands, even if they begin with the - character.

• The GNU C Library > 25.1.1 Program Argument Syntax Conventions

  The argument -- terminates all options; any following arguments are treated as non-option arguments, even if they begin with a hyphen.

• Bash Reference Manual > 4 Shell Builtin Commands

  Unless otherwise noted, each builtin command documented as accepting options preceded by ‘-’ accepts ‘--’ to signify the end of the options. The :, true, false, and test/[ builtins do not accept options and do not treat ‘--’ specially. The exit, logout, return, break, continue, let, and shift builtins accept and process arguments beginning with ‘-’ without requiring ‘--’. Other builtins that accept arguments but are not specified as accepting options interpret arguments beginning with ‘-’ as invalid options and require ‘--’ to prevent this interpretation.