From 7fdf39e8770b435e3d240b0e700b5332237bfe05 Mon Sep 17 00:00:00 2001 From: Jeremy Meng Date: Tue, 17 Aug 2021 14:36:04 -1000 Subject: [PATCH 1/2] Update ref docs of public API --- .../review/container-registry.api.md | 27 --------- .../src/containerRegistryClient.ts | 14 +++-- .../src/containerRepository.ts | 34 +++++++---- .../container-registry/src/models.ts | 31 +++++++++- .../src/registryArtifact.ts | 59 ++++++++++--------- 5 files changed, 90 insertions(+), 75 deletions(-) diff --git a/sdk/containerregistry/container-registry/review/container-registry.api.md b/sdk/containerregistry/container-registry/review/container-registry.api.md index 7510e634f024..31962b1508ce 100644 --- a/sdk/containerregistry/container-registry/review/container-registry.api.md +++ b/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" } diff --git a/sdk/containerregistry/container-registry/src/containerRegistryClient.ts b/sdk/containerregistry/container-registry/src/containerRegistryClient.ts index d2a3f9a80eca..ca7b62b36f44 100644 --- a/sdk/containerregistry/container-registry/src/containerRegistryClient.ts +++ b/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 { * "", * ); * ``` - * @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 diff --git a/sdk/containerregistry/container-registry/src/containerRepository.ts b/sdk/containerregistry/container-registry/src/containerRepository.ts index 72829fedbadb..31e0b4d8afd2 100644 --- a/sdk/containerregistry/container-registry/src/containerRepository.ts +++ b/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; /** - * 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; /** - * Updates repository attributes. + * Updates the properties of this repository. * * Example usage: * @@ -101,6 +105,8 @@ export interface ContainerRepository { ): Promise; /** * 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: * diff --git a/sdk/containerregistry/container-registry/src/models.ts b/sdk/containerregistry/container-registry/src/models.ts index f883e633e117..b9ade9e8f848 100644 --- a/sdk/containerregistry/container-registry/src/models.ts +++ b/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" } diff --git a/sdk/containerregistry/container-registry/src/registryArtifact.ts b/sdk/containerregistry/container-registry/src/registryArtifact.ts index 2ce551da854e..d5e1d1dc9243 100644 --- a/sdk/containerregistry/container-registry/src/registryArtifact.ts +++ b/sdk/containerregistry/container-registry/src/registryArtifact.ts @@ -41,13 +41,13 @@ export interface GetTagPropertiesOptions extends OperationOptions {} * Options for the `updateTagProperties` method of `RegistryArtifact`. */ export interface UpdateTagPropertiesOptions extends OperationOptions { - /** Delete enabled */ + /** Whether or not this tag can be deleted */ canDelete?: boolean; - /** Write enabled */ + /** Whether or not this tag can be written to */ canWrite?: boolean; - /** List enabled */ + /** Whether or not to include this tag when listing tags */ canList?: boolean; - /** Read enabled */ + /** Whether or not this tag can be read */ canRead?: boolean; } @@ -55,13 +55,13 @@ export interface UpdateTagPropertiesOptions extends OperationOptions { * Options for the `updateManifestProperties` method of `RegistryArtifact`. */ export interface UpdateManifestPropertiesOptions extends OperationOptions { - /** Delete enabled */ + /** Whether or not this manifest can be deleted */ canDelete?: boolean; - /** Write enabled */ + /** Whether or not this manifest can be written to */ canWrite?: boolean; - /** List enabled */ + /** Whether or not to include this manifest when listing manifest properties */ canList?: boolean; - /** Read enabled */ + /** Whether or not this manifest can be read */ canRead?: boolean; } @@ -74,7 +74,12 @@ export interface ListTagPropertiesOptions extends OperationOptions { } /** - * The helper used to interact with the Container Registry artifact. + * `Artifact` is the general term for items stored in a container registry, + * and can include Docker images or other Open Container Initiative (OCI) artifact types. + * + * The {@link RegistryArtifact} interface is a helper that groups information and operations about an image + * or artifact in a container registry. + * */ export interface RegistryArtifact { /** @@ -90,25 +95,25 @@ export interface RegistryArtifact { */ readonly fullyQualifiedReference: string; /** - * Deletes this artifact. + * Deletes this registry artifact by deleting its manifest. * @param options - */ delete(options?: DeleteArtifactOptions): Promise; /** - * Deletes a tag. - * @param tag - the name of the tag to be deleted. + * Deletes a tag. This removes the tag from the artifact and its manifest. + * @param tag - the name of the tag to delete. * @param options - */ deleteTag(tag: string, options?: DeleteTagOptions): Promise; /** - * Retrieves properties of this registry artifact. + * Retrieves the properties of the manifest that uniquely identifies this artifact. * @param options - */ getManifestProperties( options?: GetManifestPropertiesOptions ): Promise; /** - * Updates artifact manifest properties. + * Updates the properties of the artifact's manifest. * * Example usage: * @@ -128,13 +133,13 @@ export interface RegistryArtifact { options: UpdateManifestPropertiesOptions ): Promise; /** - * Retrieves properties of a tag. + * Retrieves the properties of the specified tag. * @param tag - the tag to retrieve properties. * @param options - */ getTagProperties(tag: string, options?: GetTagPropertiesOptions): Promise; /** - * Updates tag properties. + * Updates the properties of a given tag. * * Example usage: * @@ -148,7 +153,7 @@ export interface RegistryArtifact { * canWrite: false * }); * ``` - * @param tag - name of the tag + * @param tag - name of the tag to update properties on * @param options - */ updateTagProperties( @@ -156,7 +161,7 @@ export interface RegistryArtifact { options: UpdateTagPropertiesOptions ): Promise; /** - * Returns an async iterable iterator to list tag properties. + * Returns an async iterable iterator to list the tags that uniquely identify this artifact and the properties of each. * * Example using `for-await-of` syntax: * @@ -270,7 +275,7 @@ export class RegistryArtifactImpl { } /** - * Deletes this artifact. + * Deletes this registry artifact by deleting its manifest. * @param options - */ public async delete(options: DeleteArtifactOptions = {}): Promise { @@ -291,8 +296,8 @@ export class RegistryArtifactImpl { } /** - * Deletes a tag. - * @param tag - the name of the tag to be deleted. + * Deletes a tag. This removes the tag from the artifact and its manifest. + * @param tag - the name of the tag to delete. * @param options - */ public async deleteTag(tag: string, options: DeleteTagOptions = {}): Promise { @@ -313,7 +318,7 @@ export class RegistryArtifactImpl { } /** - * Retrieves properties of this registry artifact. + * Retrieves the properties of the manifest that uniquely identifies this artifact. * @param options - */ public async getManifestProperties( @@ -337,7 +342,7 @@ export class RegistryArtifactImpl { } /** - * Updates artifact manifest properties. + * Updates the properties of the artifact's manifest. * * Example usage: * @@ -382,7 +387,7 @@ export class RegistryArtifactImpl { } /** - * Retrieves properties of a tag. + * Retrieves the properties of the specified tag. * @param tag - the tag to retrieve properties. * @param options - */ @@ -410,7 +415,7 @@ export class RegistryArtifactImpl { } /** - * Updates tag properties. + * Updates the properties of a given tag. * * Example usage: * @@ -424,7 +429,7 @@ export class RegistryArtifactImpl { * canWrite: false * }); * ``` - * @param tag - name of the tag + * @param tag - name of the tag to update properties on * @param options - */ public async updateTagProperties( @@ -460,7 +465,7 @@ export class RegistryArtifactImpl { } /** - * Returns an async iterable iterator to list tag properties. + * Returns an async iterable iterator to list the tags that uniquely identify this artifact and the properties of each. * * Example using `for-await-of` syntax: * From 3b03c0d1fc83bde1f1051d263be24dcc7ab3f0de Mon Sep 17 00:00:00 2001 From: Jeremy Meng Date: Wed, 18 Aug 2021 07:44:38 -1000 Subject: [PATCH 2/2] Fix linting error --- .../container-registry/src/containerRepository.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/containerregistry/container-registry/src/containerRepository.ts b/sdk/containerregistry/container-registry/src/containerRepository.ts index 31e0b4d8afd2..b8c48c40ef26 100644 --- a/sdk/containerregistry/container-registry/src/containerRepository.ts +++ b/sdk/containerregistry/container-registry/src/containerRepository.ts @@ -55,7 +55,7 @@ export interface UpdateRepositoryPropertiesOptions extends OperationOptions { * 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 + * The {@link ContainerRepository} interface is a helper that groups information and operations about a repository in this * container registry. */ export interface ContainerRepository {