[ContainerRegistry] improve ref docs of public API

sdk/containerregistry/container-registry/review/container-registry.api.md

@@ -116,63 +116,36 @@ export interface GetTagPropertiesOptions extends OperationOptions {
 
 // @public
 export enum KnownArtifactArchitecture {
-    // (undocumented)
     Amd64 = "amd64",
-    // (undocumented)
     Arm = "arm",
-    // (undocumented)
     Arm64 = "arm64",
-    // (undocumented)
     I386 = "386",
-    // (undocumented)
     Mips = "mips",
-    // (undocumented)
     Mips64 = "mips64",
-    // (undocumented)
     Mips64Le = "mips64le",
-    // (undocumented)
     MipsLe = "mipsle",
-    // (undocumented)
     Ppc64 = "ppc64",
-    // (undocumented)
     Ppc64Le = "ppc64le",
-    // (undocumented)
     RiscV64 = "riscv64",
-    // (undocumented)
     S390X = "s390x",
-    // (undocumented)
     Wasm = "wasm"
 }
 
 // @public
 export enum KnownArtifactOperatingSystem {
-    // (undocumented)
     Aix = "aix",
-    // (undocumented)
     Android = "android",
-    // (undocumented)
     Darwin = "darwin",
-    // (undocumented)
     Dragonfly = "dragonfly",
-    // (undocumented)
     FreeBsd = "freebsd",
-    // (undocumented)
     Illumos = "illumos",
-    // (undocumented)
     iOS = "ios",
-    // (undocumented)
     JS = "js",
-    // (undocumented)
     Linux = "linux",
-    // (undocumented)
     NetBsd = "netbsd",
-    // (undocumented)
     OpenBsd = "openbsd",
-    // (undocumented)
     Plan9 = "plan9",
-    // (undocumented)
     Solaris = "solaris",
-    // (undocumented)
     Windows = "windows"
 }
 

sdk/containerregistry/container-registry/src/containerRegistryClient.ts

@@ -74,7 +74,7 @@ export class ContainerRegistryClient {
    *    new DefaultAzureCredential()
    * );
    * ```
-   * @param endpoint - the URL to the Container Registry endpoint
+   * @param endpoint - the URL endpoint of the container registry
    * @param credential - used to authenticate requests to the service
    * @param options - optional configuration used to send requests to the service
    */
@@ -87,6 +87,8 @@ export class ContainerRegistryClient {
   /**
    * Creates an instance of a ContainerRegistryClient to interact with
    * an Azure Container Registry that has anonymous pull access enabled.
+   * Only operations that support anonymous access are enabled. Other service
+   * methods will throw errors.
    *
    * Example usage:
    * ```ts
@@ -96,7 +98,7 @@ export class ContainerRegistryClient {
    *    "<container registry API endpoint>",
    * );
    * ```
-   * @param endpoint - the URL to the Container Registry endpoint
+   * @param endpoint - the URL endpoint of the container registry
    * @param options - optional configuration used to send requests to the service
    */
   constructor(endpoint: string, options?: ContainerRegistryClientOptions);
@@ -145,7 +147,7 @@ export class ContainerRegistryClient {
   }
 
   /**
-   * Deletes the repository identified by the given name.
+   * Deletes the repository identified by the given name and all associated artifacts.
    *
    * @param repositoryName - the name of repository to delete
    * @param options - optional configuration for the operation
@@ -174,7 +176,7 @@ export class ContainerRegistryClient {
   }
 
   /**
-   * Returns an artifact for given repository name, and a tag or digest.
+   * Returns an instance of {@link RegistryArtifact} for calling service methods related to the artifact specified by `repositoryName` and `tagOrDigest`.
    *
    * @param repositoryName - the name of repository
    * @param tagOrDigest - tag or digest of the artifact to retrieve
@@ -193,7 +195,7 @@ export class ContainerRegistryClient {
   }
 
   /**
-   * Returns an instance of {@link ContainerRepository} that interacts with a container registry repository.
+   * Returns an instance of {@link ContainerRepository} for calling service methods related to the repository specified by `repositoryName`.
    *
    * @param repositoryName - the name of repository
    */
@@ -206,7 +208,7 @@ export class ContainerRegistryClient {
   }
 
   /**
-   * Returns an async iterable iterator to list repository names.
+   * Returns an async iterable iterator to list names of repositories in this registry.
    *
    * Example usage:
    * ```javascript

sdk/containerregistry/container-registry/src/containerRepository.ts

@@ -39,20 +39,24 @@ export interface GetRepositoryPropertiesOptions extends OperationOptions {}
  * Options for the `setProperties` method of `ContainerRepository`.
  */
 export interface UpdateRepositoryPropertiesOptions extends OperationOptions {
-  /** Delete enabled */
+  /** Whether or not this repository can be deleted */
   canDelete?: boolean;
-  /** Write enabled */
+  /** Whether or not this repository can be written to */
   canWrite?: boolean;
-  /** List enabled */
+  /** Whether or not include this repository when listing repositories */
   canList?: boolean;
-  /** Read enabled */
+  /** Whether or not this repository can be read */
   canRead?: boolean;
   /** Enables Teleport functionality on new images in the repository improving Container startup performance */
   teleportEnabled?: boolean;
 }
 
 /**
- * The helper used to interact with the Container Registry service.
+ * A `repository` in a container registry is a logical grouping of images or artifacts that share the same name.  For example,
+ * different versions of a `hello-world` application could have tags `v1` and `v2`, and be grouped by the repository `hello-world`.
+ *
+ * The {@link ContainerRepository} interface is a helper that groups information and operations about a repository in this
+ * container registry.
  */
 export interface ContainerRepository {
   /**
@@ -64,23 +68,23 @@ export interface ContainerRepository {
    */
   readonly name: string;
   /**
-   * Deletes this repository.
+   * Deletes this repository and all artifacts that are part of its logical group.
    *
    * @param options - optional configuration for the operation
    */
   delete(options?: DeleteRepositoryOptions): Promise<void>;
   /**
-   * Returns an instance of RegistryArtifact.
+   * Returns an helper instance of {@link RegistryArtifact} for the given tag or digest.
    * @param tagOrDigest - the tag or digest of the artifact
    */
   getArtifact(tagOrDigest: string): RegistryArtifact;
   /**
-   * Retrieves properties of this repository.
+   * Retrieves the properties of this repository.
    * @param options -
    */
   getProperties(options?: GetRepositoryPropertiesOptions): Promise<ContainerRepositoryProperties>;
   /**
-   * Updates repository attributes.
+   * Updates the properties of this repository.
    *
    * Example usage:
    *
@@ -101,6 +105,8 @@ export interface ContainerRepository {
   ): Promise<ContainerRepositoryProperties>;
   /**
    * Returns an async iterable iterator to list manifest properties.
+   * This is useful for determining the collection of artifacts associated with
+   * this repository, as each artifact is uniquely identified by its manifest.
    *
    * Example using `for-await-of` syntax:
    *
@@ -175,7 +181,7 @@ export class ContainerRepositoryImpl {
   }
 
   /**
-   * Deletes this repository.
+   * Deletes this repository and all artifacts that are part of its logical group.
    *
    * @param options - optional configuration for the operation
    */
@@ -193,7 +199,7 @@ export class ContainerRepositoryImpl {
   }
 
   /**
-   * Returns an instance of {@link RegistryArtifact} that interacts with a container registry artifact.
+   * Returns an helper instance of {@link RegistryArtifact} for the given tag or digest.
    * @param tagOrDigest - the tag or digest of the artifact
    */
   public getArtifact(tagOrDigest: string): RegistryArtifact {
@@ -204,7 +210,7 @@ export class ContainerRepositoryImpl {
   }
 
   /**
-   * Retrieves properties of this repository.
+   * Retrieves the properties of this repository.
    * @param options -
    */
   public async getProperties(
@@ -223,7 +229,7 @@ export class ContainerRepositoryImpl {
   }
 
   /**
-   * Updates repository attributes.
+   * Updates the properties of this repository.
    *
    * Example usage:
    *
@@ -266,6 +272,8 @@ export class ContainerRepositoryImpl {
 
   /**
    * Returns an async iterable iterator to list manifest properties.
+   * This is useful for determining the collection of artifacts associated with
+   * this repository, as each artifact is uniquely identified by its manifest.
    *
    * Example using `for-await-of` syntax:
    *

sdk/containerregistry/container-registry/src/models.ts

@@ -6,41 +6,68 @@ export { ContainerRepositoryProperties, ArtifactTagProperties } from "./generate
 import { ArtifactTagProperties } from "./generated";
 
 /**
- * Defines known {@link ArtifactArchitecture} that the service supports.
+ * Defines known artifact architectures that the service supports.
  */
 export enum KnownArtifactArchitecture {
+  /** i386 */
   I386 = "386",
+  /** AMD64 */
   Amd64 = "amd64",
+  /** ARM */
   Arm = "arm",
+  /** ARM64 */
   Arm64 = "arm64",
+  /** MIPS */
   Mips = "mips",
+  /** MIPSLE */
   MipsLe = "mipsle",
+  /** MIPS64 */
   Mips64 = "mips64",
+  /** MIPS64LE */
   Mips64Le = "mips64le",
+  /** PPC64 */
   Ppc64 = "ppc64",
+  /** PPC64LE */
   Ppc64Le = "ppc64le",
+  /** RISCv64 */
   RiscV64 = "riscv64",
+  /** s390x */
   S390X = "s390x",
+  /** Wasm */
   Wasm = "wasm"
 }
 
 /**
- * Defines known {@link ArtifactOperatingSystem} values that the service supports.
+ * Defines known artifact platform's operating systems that the service supports.
  */
 export enum KnownArtifactOperatingSystem {
+  /** Aix */
   Aix = "aix",
+  /** Android */
   Android = "android",
+  /** Darwin */
   Darwin = "darwin",
+  /** Dragonfly */
   Dragonfly = "dragonfly",
+  /** FreeBSD */
   FreeBsd = "freebsd",
+  /** Illumos */
   Illumos = "illumos",
+  /** iOS */
   iOS = "ios",
+  /** JS */
   JS = "js",
+  /** Linux */
   Linux = "linux",
+  /** NetBSD */
   NetBsd = "netbsd",
+  /** OpenBSD */
   OpenBsd = "openbsd",
+  /** Plan9 */
   Plan9 = "plan9",
+  /** Solaris */
   Solaris = "solaris",
+  /** Windows */
   Windows = "windows"
 }