Improve CompletionKind DocC

[rgoldberg]

Improve CompletionKind DocC.

Do not merge until after #738 has been merged.

Resolve #739

Checklist

• I've added at least one test that validates that my change is working, if appropriate
• I've followed the code style of the rest of the project
• I've read the Contribution Guidelines
• I've updated the documentation if necessary

[natecook1000]

These documentation additions are great, @rgoldberg – thanks so much! A few notes on the specifics below…

[natecook1000]

We can skip the doc comments on the enum and its cases, since they're all internal.

[natecook1000]

When it sounds natural, we try to just describe the argument in English words rather than using types or parameter names — something like:

Suggested change

	/// The completion candidates are the elements of `words`.
	/// The completion candidates are the strings in the given array.

[natecook1000]

The one-line summary is what shows up as an abstract when an API is included as a list, so this would just be a sentence fragment. Let's use a full sentence ("...directory and file names, filtered by the given list of extensions"?) and then include the detail about exactly which file names in the body of the doc comment.

[natecook1000]

I like these cues about how/where the different completion configurations are used 👍🏻

[rgoldberg]

@natecook1000 I've pushed commits that should address all of your comments.

Unfortunately, I was lax on this PR like I was on the fish PR; I forgot that there are a few things that I must check first, then for which I must update the documentation (& possibly the code). I have therefore included TODO notes in the DocC in such places; I've also switched this PR to a draft.

In my forthcoming PR that adds the 2 index parameters to custom completion closures, there were some DocC improvements for custom completions that were unrelated to the code changes in that PR; I have now added them in this PR. This significantly improves the DocC, but also significantly lengthens it, especially with exceptions to the standard behavior (which might not be 100% accurate as of now, but I'll revisit the listed exceptions as soon as I'm done with fish & the other DocC issues here).

Feel free to look over everything soon to provide feedback, or feel free to wait until I've fixed up all the TODOs (at which time I will mark the PR as ready for review). I'll finish the DocC here only after I've fixed up the fish PR.

[rgoldberg]

@natecook1000

Splitting PRs vs. munging very small issues together

After looking through the possible zsh setopt settings, I want to change a few for the zsh scripts.

Should I create a new PR for the zsh setopt changes, then rebase this PR on main after that PR has been merged into main, or can I just make the zsh setopt settings in this PR?

The latter has less overhead, but it munges a few glob settings into a documentation PR.

I want to follow whatever procedure you prefer (in the future, I'll default to whichever you prefer: splitting things up vs. munging small things together when convenient).

Postponing other shell settings

I'd like to merge this documentation before looking through additional settings for any of the shells.

The settings are better than they were, and the documentation is much improved.

I think there are more pressing issues to fix than searching through tons of obscure settings & documenting them now.

Most people wouldn't even have documented the settings, so I think we're ahead of the game despite not being 100% configured / documented (there are so many shell settings that I wouldn't be able to go through all of them quickly for 3 shells).

bash 4

I want to test the script on bash 4 so I could verify that a bit of documentation is correct. I couldn't easily install bash 4 on my Mac.

Do you know of any binary distributions of bash 4, or anyone who can easily build bash 4 for macOS 12 on Intel so I can quickly test it?

I got errors trying to build it on my computer; I'd rather not go down a rabbit hole if I can easily obtain bash 4 from someone else.

Thanks.

[rgoldberg]

@natecook1000 If you have time, can you advise on the issues mentioned in the comment above? #740 (comment)

Would be good for me to test / finish this while you're reviewing my fish PR after that's ready.

[natecook1000]

There's enough here that it would be good to use subheads for the shell-specific notes, once the discussion that applies across the board is finished:

### Bash

In bash 3?-, a process substitution...

### Fish

In fish 3-, due to a bug...

etc

[rgoldberg]

@natecook1000 I missed this comment before. I'll include the subheadings now.

[natecook1000]

Re: Splitting PRs vs. munging very small issues together

I'm honestly happy to work with whatever makes sense to you – the separate PRs for different shell improvements have been nice to work with, and since you're taking over the effort to base completion generation on the tool info, there isn't much contention around this part of the code base. Why don't you go with what makes sense, and if something looks unreasonably large we can talk about how to split it up?

Postponing other shell settings

Agreed on all counts - happy for you to focus on the issues that are more pressing!

Bash 4

I don't know of any binary distributions, and it looks like I only have easy access to versions 3 and 5 — I'll ask around! Not a dealbreaker if we have to go without testing this version, since it seems unlikely to exist that frequently in the wild.

[rgoldberg]

@natecook1000 Thanks for the feedback.

I'll probably munge the settings changes into the documentation PR, because they're very small, and I will probably not be able to work on SAP much right now, so I'd rather save time instead of coordinating multiple PRs, rebasing, etc.

The main interest I have in bash 4 is to ensure that the DocC is correct & concise, which is easier if I know when bash behavior changed (I'll probably check only bash 4 & 5, not minor versions or smaller increments).

Thanks for the help.

[rgoldberg]

@natecook1000 Did you have any luck finding a binary of bash 4? Or any way in which I can easily compile it myself? I just need it to test some features to ensure that my revised documentation is correct.

FYI: I have an M4 Mac Studio now, so I have more build options as I am running the latest macOS & Xcode, and can run some other software that my old Mac mini 2014 couldn't. I still have my Mac mini 2014, though, so I can still run or build x86_64 binaries natively, if you only have binaries or working build instructions for x86_64.

Thanks for any help.