Add docs; rename function name

pkg/cmd/api/api.go

@@ -265,7 +265,7 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command
 				return err
 			}
 
-			opts.RequestPath = escapePathWithPackageName(opts.RequestPath)
+			opts.RequestPath = escapePackageNameInPath(opts.RequestPath)
 
 			if runF != nil {
 				return runF(&opts)
@@ -693,9 +693,29 @@ func previewNamesToMIMETypes(names []string) string {
 	return strings.Join(types, ", ")
 }
 
+// The package name part in the `packages` endpoints may contain slashes and
+// other characters that need to be URL encoded.
+//
+// The `escapePackageNameInPath` function extracts and normalizes package names
+// in the path. The regex `pathWithPackageNameRE` is being used to extract the
+// package name with a capture group named `package`.
+//
+// See https://docs.github.com/en/rest/packages/packages APIs for more details.
+//
+// Here's an example:
+//
+// The package name `orders/cache` needs to be URL encoded because it contains
+// a slash `/`. The `escapePackageNameInPath` function will extract the
+// `orders/cache` part, perform the URL encoding, and return the normalized API
+// endpoint with `%2F` replacing the slash `/` in the package name part only.
+//
+// - Package name: `orders/cache`
+// - API endpoint: `/users/USER/packages/container/orders/cache`
+// - Normalized:   `/users/USER/packages/container/orders%2Fcache`
+
 var pathWithPackageNameRE = regexp.MustCompile(`^\/(?:orgs|user|users)(?:\/.*)?\/packages\/(?:npm|maven|rubygems|docker|nuget|container)\/(?<package>.*?)(?:\/(?:restore|versions)|$)`)
 
-func escapePathWithPackageName(path string) string {
+func escapePackageNameInPath(path string) string {
 	matches := pathWithPackageNameRE.FindStringSubmatch(path)
 	if len(matches) > 0 {
 		i := pathWithPackageNameRE.SubexpIndex("package")