Clarify helptext for search prs regarding archived repos

[stuart-leitch]

See #8699

The behaviour of the --archived flag to gh search prs is a little unintuitive. This tiny PR updates to helptext to try to make this more obvious for new users.

At present the --archived flag is defined via NilBoolFlag. Ideally the helptest would use StringEnumFlag instead to declare the --archived flag, but this is a bit beyond my capabilities to do with confidence :)

[williammartin]

Sorry for the slow response here. Thanks a lot for this! I added a comment on the issue that I would like to see this change for both search issues and search prs, and additionally an update on the flag text for search repos to indicate the possible values as you have done already.

At present the --archived flag is defined via NilBoolFlag. Ideally the helptest would use StringEnumFlag instead to declare the --archived flag, but this is a bit beyond my capabilities to do with confidence :)

Maybe. Unfortunately because it's a NilBoolFlag the following has always been valid: gh search issues --author @me --archived. This means if we used a StringEnumFlag we would need to handle the empty string as well, and if we did that we also need to distinguish from the flag being absent which means we'd need a NilStringEnumFlag 😰

[stuart-leitch]

Replicated the helptext changes I made to gh search prs across to gh search repos and gh search issues as per suggestion above. Good to keep these consistent.

One general comment, if you will. Command line helptext is always terse. I note that the online manual simply replicates the helptext, and wonder if there's an opportunity being missed to have more expansive explanation of some of the API behaviour.

[williammartin]

LGTM thanks for improving our docs!

[williammartin]

One general comment, if you will. Command line helptext is always terse. I note that the online manual simply replicates the helptext, and wonder if there's an opportunity being missed to have more expansive explanation of some of the API behaviour.

Perhaps. I think historically we've tried to keep the CLI help, the manpages and the online manual in sync so that people can consume the docs in whichever their preferred mode is. I do feel like the latter two serve themselves a bit better for thorough reading than the help but I don't know how we would make more detailed reading available for discovery. Definitely worth thinking about though.