diff --git a/third_party/docfx-doclet-143274/pom.xml b/third_party/docfx-doclet-143274/pom.xml index a6263964..0b702e4a 100644 --- a/third_party/docfx-doclet-143274/pom.xml +++ b/third_party/docfx-doclet-143274/pom.xml @@ -94,9 +94,9 @@ - com.coveo + com.spotify.fmt fmt-maven-plugin - 2.13 + 2.23 true diff --git a/third_party/docfx-doclet-143274/src/main/java/com/google/docfx/doclet/RepoMetadata.java b/third_party/docfx-doclet-143274/src/main/java/com/google/docfx/doclet/RepoMetadata.java index a2c378b9..c9408fea 100644 --- a/third_party/docfx-doclet-143274/src/main/java/com/google/docfx/doclet/RepoMetadata.java +++ b/third_party/docfx-doclet-143274/src/main/java/com/google/docfx/doclet/RepoMetadata.java @@ -46,6 +46,9 @@ public class RepoMetadata { @SerializedName("api_id") private String apiId; + @SerializedName("recommended_package") + private String recommendedPackage; + private String artifactId; public String getNamePretty() { @@ -80,6 +83,10 @@ public void setProductDocumentationUri(String productDocumentationUri) { this.productDocumentationUri = productDocumentationUri; } + public Optional getRecommendedPackage() { + return Optional.ofNullable(this.recommendedPackage); + } + public String getApiDescription() { return this.apiDescription; } diff --git a/third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/PackageBuilder.java b/third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/PackageBuilder.java index bba0e5b6..d5f89216 100644 --- a/third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/PackageBuilder.java +++ b/third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/PackageBuilder.java @@ -35,7 +35,7 @@ PackageOverviewFile buildPackageOverviewFile( PackageElement packageElement, RepoMetadata repoMetadata, String artifactVersion, - String recommendedApiVersion) { + String recommendedPackage) { String status = packageLookup.extractStatus(packageElement); String fileName = packageElement.getQualifiedName() + ".md"; PackageOverviewFile packageOverviewFile = @@ -48,7 +48,7 @@ PackageOverviewFile buildPackageOverviewFile( packageLookup, referenceBuilder, artifactVersion, - recommendedApiVersion); + recommendedPackage); return packageOverviewFile; } } diff --git a/third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/PackageOverviewFile.java b/third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/PackageOverviewFile.java index 19758662..862f5cb3 100644 --- a/third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/PackageOverviewFile.java +++ b/third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/PackageOverviewFile.java @@ -55,9 +55,13 @@ public class PackageOverviewFile { // This is only set if the package is not a GA package private String PRERELEASE_IMPLICATIONS = ""; - private String recommendedApiVersion; + // Uses the `recommended_package` field set in the RepoMetadata file if set; otherwise computes + // it. + private String recommendedPackage; - // This is only set if the package is not the latest GA package + private String recommendedPackageLink; + + // This is only set if the package is not the recommended package private String RECOMMENDED_VERSION = ""; // This is only set if the package is a stub package @@ -81,19 +85,22 @@ public PackageOverviewFile( PackageLookup packageLookup, ReferenceBuilder referenceBuilder, String artifactVersion, - String recommendedApiVersion) { + String recommendedPackage) { this.outputPath = outputPath; this.fileName = fileName; this.packageElement = packageElement; - this.recommendedApiVersion = recommendedApiVersion; + this.recommendedPackage = recommendedPackage; String packageURIPath = fileName.replace(".md", ""); this.PACKAGE_HEADER = "# Package " + packageURIPath + " (" + artifactVersion + ")\n"; - // This will always link to the latest version of the package classes String cloudRADChildElementLinkPrefix = - "https://cloud.google.com/java/docs/reference/" + repoMetadata.getArtifactId() + "/latest/"; + "https://cloud.google.com/java/docs/reference/" + + repoMetadata.getArtifactId() + + "/" + + artifactVersion + + "/"; String packageURIPathGithub = packageURIPath.replace('.', '/'); String githubSourcePackageLink = @@ -103,56 +110,49 @@ public PackageOverviewFile( + "/src/main/java/" + packageURIPathGithub; + String cgcRootUri = "https://cloud.google.com/java/docs/reference/"; + this.recommendedPackageLink = + cgcRootUri + + repoMetadata.getArtifactId() + + "/" + + artifactVersion + + "/" + + this.recommendedPackage; // If the package status is not a GA version, then add a disclaimer around prerelease // implications if (status != null) { this.PRERELEASE_IMPLICATIONS = "## Prerelease Implications\n\n" - + "This package is a prerelease version! Use with caution.\n" - + "Prerelease versions are considered unstable as they may be shut down. You can read more about [Cloud API versioning strategy here](https://cloud.google.com/apis/design/versioning).\n" - + "Each Cloud Java client library may contain multiple packages. Each package containing a version number in its name corresponds to a published version of the service.\n" - + "We recommend using the latest stable version for new production applications, which can be identified by the largest numeric version that does not contain a suffix.\n" - + "For example, if a client library has two packages: `v1` and `v2alpha`, then the latest stable version is `v1`.\n" - + "If you use an unstable release, breaking changes may be introduced when upgrading.\n\n"; + + "This package is a prerelease version! Use with caution.\n\n" + + "Prerelease versions are considered unstable as they may be shut down and/or subject to breaking changes when upgrading.\n" + + "Use them only for testing or if you specifically need their experimental features.\n\n"; } - // This regex captures the package path before the version (if it exists) and the version - Pattern pattern = Pattern.compile("(.*?)(v\\d+.*?)(?:\\.|$)"); - ImmutableList packageVersionURIInfo = - extractPackageBaseURIBeforeVersion(packageURIPath, pattern); - String basePackageURI = packageVersionURIInfo.get(0).toString(); - String packageVersion = packageVersionURIInfo.get(1).toString(); - // Build link to the Cloud RAD link for the recommended package - String recommendedPackageVersionLink = - cloudRADChildElementLinkPrefix + basePackageURI + recommendedApiVersion; - - // A package is not the latest GA version if it is a prerelease version, or if it is a GA - // version that is not the same as the recommended Api version - if (basePackageURI != "N/A") { - if (status != null || (!packageVersion.equals(this.recommendedApiVersion))) { - this.RECOMMENDED_VERSION = - "## This package is not the latest GA version! \n\n" - + " For this library, we recommend using the [package](" - + recommendedPackageVersionLink - + ")" - + " associated with API version " - + this.recommendedApiVersion - + " for new applications.\n" - + "\n"; - } + // If a package is not the same as the recommended package, add a disclaimer. If the recommended + // package does not exist, then do not set the disclaimer. + if (!this.recommendedPackage.isEmpty() + && !packageElement.getQualifiedName().toString().equals(this.recommendedPackage)) { + this.RECOMMENDED_VERSION = + "## This package is not the recommended entry point to using this client library!\n\n" + + " For this library, we recommend using [" + + recommendedPackage + + "](" + + recommendedPackageLink + + ")" + + " for new applications.\n" + + "\n"; } - // If recommended version package URI exists, link to it for the Stub class as well - if (basePackageURI != "N/A" + // Link to recommended package (if it exists) for the Stub class as well + if (!this.recommendedPackage.isEmpty() && String.valueOf(this.packageElement.getQualifiedName()).contains("stub")) { this.STUB_IMPLICATIONS = "## Stub Package Implications\n\n" + "This package is a a base stub class. It is for advanced usage and reflects the underlying API directly.\n" - + "We generally recommend using non-stub, latest GA package, such as [" - + basePackageURI - + recommendedApiVersion + + "We generally recommend using the non-stub, latest GA package, such as [" + + recommendedPackage + "](" - + recommendedPackageVersionLink + + recommendedPackageLink + ")" + ". Use with caution.\n"; } else if (String.valueOf(this.packageElement.getQualifiedName()).contains("stub")) { diff --git a/third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/YmlFilesBuilder.java b/third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/YmlFilesBuilder.java index 4a06a9c7..f0ddb1e8 100644 --- a/third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/YmlFilesBuilder.java +++ b/third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/YmlFilesBuilder.java @@ -19,8 +19,9 @@ import com.microsoft.util.ElementUtil; import com.microsoft.util.FileUtil; import java.util.ArrayList; -import java.util.HashSet; +import java.util.HashMap; import java.util.List; +import java.util.Optional; import java.util.stream.Collectors; import javax.lang.model.element.PackageElement; import jdk.javadoc.doclet.DocletEnvironment; @@ -105,7 +106,7 @@ public boolean build() { artifactVersion, librariesBomVersion, repoMetadataFilePath, - processor.recommendedApiVersion); + processor.recommendedPackage); FileUtil.dumpToFile(libraryOverviewFile); } return true; @@ -131,7 +132,10 @@ class Processor { private final List allPackages = elementUtil.extractPackageElements(environment.getIncludedElements()); - private String recommendedApiVersion = ""; + private ApiVersion recommendedApiVersion; + + // If set in RepoMetadata, use that value. Otherwise, calculate based on recommendedApiVersion + private String recommendedPackage = ""; private RepoMetadata repoMetadata = new RepoMetadata(); @@ -143,15 +147,25 @@ void process() { .filter(pkg -> !packageLookup.isApiVersionStubPackage(pkg)) .collect(Collectors.toList())); - // Get recommended ApiVersion for new Library Overview - HashSet versions = new HashSet<>(); - for (PackageElement pkg : allPackages) { - packageLookup.extractApiVersion(pkg).ifPresent(versions::add); - } - - if (!versions.isEmpty()) { - recommendedApiVersion = ApiVersion.getRecommended(versions).toString(); - } + // Use the provided recommended package in the .repo-metadata.json file, if set + recommendedPackage = + repoMetadata + .getRecommendedPackage() + .orElseGet( + () -> { + // Calculate the recommended package based on the latest stable Version ID. + HashMap packageVersions = new HashMap<>(); + for (PackageElement pkg : allPackages) { + Optional apiVersion = packageLookup.extractApiVersion(pkg); + apiVersion.ifPresent( + version -> + packageVersions.put(version, String.valueOf(pkg.getQualifiedName()))); + } + if (packageVersions.isEmpty()) return ""; + + ApiVersion recommended = ApiVersion.getRecommended(packageVersions.keySet()); + return packageVersions.get(recommended).toString(); + }); for (PackageElement element : organizedPackagesWithoutStubs.get(PackageGroup.VISIBLE)) { tocFile.addTocItem(buildPackage(element)); @@ -200,7 +214,7 @@ private TocItem buildPackage(PackageElement element) { packageTocItem.getItems().add(packageSummary); packageOverviewFiles.add( packageBuilder.buildPackageOverviewFile( - element, repoMetadata, artifactVersion, recommendedApiVersion)); + element, repoMetadata, artifactVersion, recommendedPackage)); // build classes/interfaces/enums/exceptions/annotations packageTocItem diff --git a/third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/LibraryOverviewFile.java b/third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/LibraryOverviewFile.java index 52940b0b..1495a24d 100644 --- a/third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/LibraryOverviewFile.java +++ b/third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/LibraryOverviewFile.java @@ -17,22 +17,24 @@ public class LibraryOverviewFile { // This is passed in as an environment variable private String librariesBomVersion; - // This is parsed from the packages - private String recommendedApiVersion; + private String recommendedPackageLink; - private String LIBRARY_OVERVIEW_FILE_HEADER; + // This is parsed from the .repoMetadata.json if it exists, or is calculated in ApiVersion + private String recommendedPackage; - private String LIBRARY_OVERVIEW_KEY_REFERENCE_HEADER; + private String LIBRARY_OVERVIEW_FILE_HEADER = ""; - private String LIBRARY_OVERVIEW_KEY_REFERENCE_TABLE; + private String LIBRARY_OVERVIEW_KEY_REFERENCE_HEADER = ""; - private String LIBRARY_OVERVIEW_GETTING_STARTED_SECTION; + private String LIBRARY_OVERVIEW_KEY_REFERENCE_TABLE = ""; - private String LIBRARY_OVERVIEW_CLIENT_INSTALLATION_SECTION; + private String LIBRARY_OVERVIEW_GETTING_STARTED_SECTION = ""; - private String LIBRARY_OVERVIEW_CLIENT_INSTALLATION_HEADER; + private String LIBRARY_OVERVIEW_CLIENT_INSTALLATION_SECTION = ""; - private String LIBRARY_OVERVIEW_PACKAGE_SELECTION_SECTION; + private String LIBRARY_OVERVIEW_CLIENT_INSTALLATION_HEADER = ""; + + private String LIBRARY_OVERVIEW_PACKAGE_SELECTION_SECTION = ""; public LibraryOverviewFile( String outputPath, @@ -40,17 +42,30 @@ public LibraryOverviewFile( String artifactVersion, String librariesBomVersion, String repoMetadataFilePath, - String recommendedApiVersion) { + String recommendedPackage) { this.outputPath = outputPath; this.fileName = fileName; this.artifactVersion = artifactVersion; this.librariesBomVersion = librariesBomVersion; this.repoMetadataFilePath = repoMetadataFilePath; - this.recommendedApiVersion = recommendedApiVersion; + this.recommendedPackage = recommendedPackage; RepoMetadata repoMetadata = new RepoMetadata(); repoMetadata = repoMetadata.parseRepoMetadata(this.repoMetadataFilePath); + this.recommendedPackageLink = ""; + // Compute the link to the recommended package if it exists + if (!this.recommendedPackage.isEmpty()) { + String cgcRootUri = "https://cloud.google.com/java/docs/reference/"; + this.recommendedPackageLink = + cgcRootUri + + repoMetadata.getArtifactId() + + "/" + + artifactVersion + + "/" + + this.recommendedPackage; + } + this.LIBRARY_OVERVIEW_FILE_HEADER = "# " + repoMetadata.getArtifactId() + " overview (" + artifactVersion + ")\n\n"; @@ -81,6 +96,8 @@ public LibraryOverviewFile( + "\n\n"; // For non-service libraries, these steps are not necessary + // TODO: https://github.com/googleapis/java-docfx-doclet/issues/253 : Ideally we can refactor + // for custom modules to copy from their README sections String[] runtimeLibraries = {"gax", "api-common", "common-protos", "google-cloud-core"}; if (Arrays.asList(runtimeLibraries).contains(repoMetadata.getApiShortName())) { @@ -101,109 +118,121 @@ public LibraryOverviewFile( + repoMetadata.getApiShortName() + ".googleapis.com)\n" + "- [Set up authentication](https://cloud.google.com/docs/authentication/client-libraries)\n\n"; - } - this.LIBRARY_OVERVIEW_CLIENT_INSTALLATION_HEADER = - "## Use the " - + repoMetadata.getNamePretty() - + " for Java\n" - + "To ensure that your project uses compatible versions of the libraries\n" - + "and their component artifacts, import `com.google.cloud:libraries-bom` and use\n" - + "the BOM to specify dependency versions. Be sure to remove any versions that you\n" - + "set previously. For more information about\n" - + "BOMs, see [Google Cloud Platform Libraries BOM](https://cloud.google.com/java/docs/bom).\n\n"; - - // When b/312765900 is implemented, then refactor this section to use the devsite-selector - // format. Current format is a workaround so the sanitizer doesn't remove the content. - this.LIBRARY_OVERVIEW_CLIENT_INSTALLATION_SECTION = - "### Maven\n" - + "Import the BOM in the dependencyManagement section of your pom.xml file.\n" - + "Include specific artifacts you depend on in the dependencies section, but don't\n" - + "specify the artifacts' versions in the dependencies section.\n" - + "\n" - + "The example below demonstrates how you would import the BOM and include the " - + repoMetadata.getArtifactId() - + " artifact.\n" - + "
\n"
-            + "<dependencyManagement>\n"
-            + " <dependencies>\n"
-            + "   <dependency>\n"
-            + "      <groupId>com.google.cloud</groupId>\n"
-            + "      <artifactId>libraries-bom</artifactId>\n"
-            + "      <version>"
-            + this.librariesBomVersion
-            + "</version>\n"
-            + "      <type>pom</type>\n"
-            + "      <scope>import</scope>\n"
-            + "   </dependency>\n"
-            + " </dependencies>\n"
-            + "</dependencyManagement>\n\n"
-            + "<dependencies>\n"
-            + " <dependency>\n"
-            + "   <groupId>com.google.cloud</groupId>\n"
-            + "   <artifactId>"
-            + repoMetadata.getArtifactId()
-            + "</artifactId>\n"
-            + " </dependency>\n"
-            + "</dependencies>\n"
-            + "
\n\n" - + "### Gradle\n" - + "BOMs are supported by default in Gradle 5.x or later. Add a platform\n" - + "dependency on com.google.cloud:libraries-bom and remove the version from the\n" - + "dependency declarations in the artifact's build.gradle file.\n" - + "\n" - + "The example below demonstrates how you would import the BOM and include the " - + repoMetadata.getArtifactId() - + " artifact.\n" - + "
\n"
-            + "implementation platform('com.google.cloud:libraries-bom:"
-            + librariesBomVersion
-            + "')\n"
-            + "implementation '"
-            + repoMetadata.getDistributionName()
-            + "'\n"
-            + "
\n\n" - + "The platform and enforcedPlatform keywords supply dependency versions\n" - + "declared in a BOM. The enforcedPlatform keyword enforces the dependency\n" - + "versions declared in the BOM and thus overrides what you specified.\n\n" - + "For more details of the platform and enforcedPlatform keywords Gradle 5.x or higher, see\n" - + "[Gradle: Importing Maven BOMs](https://docs.gradle.org/current/userguide/platforms.html#sub:bom_import).\n" - + "\n" - + "If you're using Gradle 4.6 or later, add\n" - + "enableFeaturePreview('IMPROVED_POM_SUPPORT') to your settings.gradle file. For details, see\n" - + "[Gradle 4.6 Release Notes: BOM import](https://docs.gradle.org/4.6/release-notes.html#bom-import).\n" - + "Versions of Gradle earlier than 4.6 don't support BOMs.

\n\n" - + "### SBT\n" - + "SBT [doesn't support BOMs](https://github.com/sbt/sbt/issues/4531). You can find\n" - + "recommended versions of libraries from a particular BOM version on the\n" - + "[dashboard](https://storage.googleapis.com/cloud-opensource-java-dashboard/com.google.cloud/libraries-bom/index.html)\n" - + "and set the versions manually.\n" - + "To use the latest version of this library, add this to your dependencies:\n" - + "
\n"
-            + "libraryDependencies += "com.google.cloud" % ""
-            + repoMetadata.getArtifactId()
-            + "" % ""
-            + artifactVersion
-            + ""\n"
-            + "
\n\n"; - - // Some client libraries do not have an underlying API service (e.g. - // google-cloud-logging-logback, google-cloud-storage-nio, google-cloud-spanner-jdbc), hence - // there is no recommended API version. - if (this.recommendedApiVersion.isEmpty()) { + this.LIBRARY_OVERVIEW_CLIENT_INSTALLATION_HEADER = + "## Use the " + + repoMetadata.getNamePretty() + + " for Java\n" + + "To ensure that your project uses compatible versions of the libraries\n" + + "and their component artifacts, import `com.google.cloud:libraries-bom` and use\n" + + "the BOM to specify dependency versions. Be sure to remove any versions that you\n" + + "set previously. For more information about\n" + + "BOMs, see [Google Cloud Platform Libraries BOM](https://cloud.google.com/java/docs/bom).\n\n"; + + // When b/312765900 is implemented, then refactor this section to use the devsite-selector + // format. Current format is a workaround so the sanitizer doesn't remove the content. + this.LIBRARY_OVERVIEW_CLIENT_INSTALLATION_SECTION = + "### Maven\n" + + "Import the BOM in the dependencyManagement section of your pom.xml file.\n" + + "Include specific artifacts you depend on in the dependencies section, but don't\n" + + "specify the artifacts' versions in the dependencies section.\n" + + "\n" + + "The example below demonstrates how you would import the BOM and include the " + + repoMetadata.getArtifactId() + + " artifact.\n" + + "
\n"
+              + "<dependencyManagement>\n"
+              + " <dependencies>\n"
+              + "   <dependency>\n"
+              + "      <groupId>com.google.cloud</groupId>\n"
+              + "      <artifactId>libraries-bom</artifactId>\n"
+              + "      <version>"
+              + this.librariesBomVersion
+              + "</version>\n"
+              + "      <type>pom</type>\n"
+              + "      <scope>import</scope>\n"
+              + "   </dependency>\n"
+              + " </dependencies>\n"
+              + "</dependencyManagement>\n\n"
+              + "<dependencies>\n"
+              + " <dependency>\n"
+              + "   <groupId>com.google.cloud</groupId>\n"
+              + "   <artifactId>"
+              + repoMetadata.getArtifactId()
+              + "</artifactId>\n"
+              + " </dependency>\n"
+              + "</dependencies>\n"
+              + "
\n\n" + + "### Gradle\n" + + "BOMs are supported by default in Gradle 5.x or later. Add a platform\n" + + "dependency on com.google.cloud:libraries-bom and remove the version from the\n" + + "dependency declarations in the artifact's build.gradle file.\n" + + "\n" + + "The example below demonstrates how you would import the BOM and include the " + + repoMetadata.getArtifactId() + + " artifact.\n" + + "
\n"
+              + "implementation platform('com.google.cloud:libraries-bom:"
+              + librariesBomVersion
+              + "')\n"
+              + "implementation '"
+              + repoMetadata.getDistributionName()
+              + "'\n"
+              + "
\n\n" + + "The platform and enforcedPlatform keywords supply dependency versions\n" + + "declared in a BOM. The enforcedPlatform keyword enforces the dependency\n" + + "versions declared in the BOM and thus overrides what you specified.\n\n" + + "For more details of the platform and enforcedPlatform keywords Gradle 5.x or higher, see\n" + + "[Gradle: Importing Maven BOMs](https://docs.gradle.org/current/userguide/platforms.html#sub:bom_import).\n" + + "\n" + + "If you're using Gradle 4.6 or later, add\n" + + "enableFeaturePreview('IMPROVED_POM_SUPPORT') to your settings.gradle file. For details, see\n" + + "[Gradle 4.6 Release Notes: BOM import](https://docs.gradle.org/4.6/release-notes.html#bom-import).\n" + + "Versions of Gradle earlier than 4.6 don't support BOMs.

\n\n" + + "### SBT\n" + + "SBT [doesn't support BOMs](https://github.com/sbt/sbt/issues/4531). You can find\n" + + "recommended versions of libraries from a particular BOM version on the\n" + + "[dashboard](https://storage.googleapis.com/cloud-opensource-java-dashboard/com.google.cloud/libraries-bom/index.html)\n" + + "and set the versions manually.\n" + + "To use the latest version of this library, add this to your dependencies:\n" + + "
\n"
+              + "libraryDependencies += "com.google.cloud" % ""
+              + repoMetadata.getArtifactId()
+              + "" % ""
+              + artifactVersion
+              + ""\n"
+              + "
\n\n"; + } + // It should be very rare that a client library does not have a recommended package + if (this.recommendedPackage.isEmpty()) { this.LIBRARY_OVERVIEW_PACKAGE_SELECTION_SECTION = ""; } else { this.LIBRARY_OVERVIEW_PACKAGE_SELECTION_SECTION = - "## Which version should I use?\n" - + "For this library, we recommend using API version " - + this.recommendedApiVersion - + " for new applications.\n" - + "\n" - + "Each Cloud Java client library may contain multiple packages. Each package containing a version number in its name corresponds to a published version of the service.\n" - + "We recommend using the latest stable version for new production applications, which can be identified by the largest numeric version that does not contain a suffix.\n" - + "For example, if a client library has two packages: `v1` and `v2alpha`, then the latest stable version is `v1`.\n" - + "If you use an unstable release, breaking changes may be introduced when upgrading.\n" - + "You can read more about [Cloud API versioning strategy here](https://cloud.google.com/apis/design/versioning).\n\n"; + "## Which version ID should I get started with?\n" + + "For this library, we recommend using " + + "[" + + this.recommendedPackage + + "](" + + this.recommendedPackageLink + + ") for new applications.\n\n" + + "### Understanding Version ID and Library Versions\n" + + "When using a Cloud client library, it's important to distinguish between two types of versions:\n" + + "- **Library Version**: The version of the software package (the client library) that helps you interact with the Cloud service. These libraries are\n" + + "released and updated frequently with bug fixes, improvements, and support for new service features and versions. The version selector at\n" + + "the top of this page represents the client library version.\n" + + "- **Version ID**: The version of the Cloud service itself (e.g. " + + repoMetadata.getNamePretty() + + "). New Version IDs are introduced infrequently, and often involve\n" + + "changes to the core functionality and structure of the Cloud service itself. The packages in the lefthand navigation represent packages tied\n" + + "to a specific Version ID of the Cloud service.\n\n" + + "### Managing Library Versions\n" + + "We recommend using the com.google.cloud:libraries-bom installation method detailed above to streamline dependency management\n" + + "across multiple Cloud Java client libraries. This ensures compatibility and simplifies updates.\n\n" + + "### Choosing the Right Version ID\n" + + "Each Cloud Java client library may contain packages tied to specific Version IDs (e.g., v1, v2alpha). For new production applications, use\n" + + "the latest stable Version ID. This is identified by the highest version number **without** a suffix (like \"alpha\" or \"beta\"). You can read more about\n" + + "[Cloud API versioning strategy here](https://cloud.google.com/apis/design/versioning).\n\n" + + "**Important**: Unstable Version ID releases (those _with_ suffixes) are subject to breaking changes when upgrading. Use them only for testing or if you specifically need their experimental features.\n\n"; } } diff --git a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.agreements.md b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.agreements.md index 37ee1cb2..9618adae 100644 --- a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.agreements.md +++ b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.agreements.md @@ -7,6 +7,10 @@ +## This package is not the recommended entry point to using this client library! + + For this library, we recommend using [com.microsoft.samples.google.v1](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/0.18.0/com.microsoft.samples.google.v1) for new applications. + ## Classes @@ -15,7 +19,7 @@ Class - + - + - + @@ -44,7 +48,7 @@ Interface - +
Description
com.microsoft.samples.agreements.AgreementDetailsCollectionOperationscom.microsoft.samples.agreements.AgreementDetailsCollectionOperations Deprecated. Use AgreementMetaData instead. @@ -23,13 +27,13 @@ Description Agreement details collection operations implementation class.
com.microsoft.samples.agreements.AgreementMetaDatacom.microsoft.samples.agreements.AgreementMetaData The AgreementMetaData provides metadata about the agreement type that partner can provide confirmation of customer acceptance.
com.microsoft.samples.agreements.ResourceCollectioncom.microsoft.samples.agreements.ResourceCollection Contains a collection of resources with JSON properties to represent the output Type of objects in collection Description
com.microsoft.samples.agreements.IAgreementDetailsCollectioncom.microsoft.samples.agreements.IAgreementDetailsCollection Deprecated. This one is deprecated :( diff --git a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.commentinheritance.md b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.commentinheritance.md index 31a00725..f07675a6 100644 --- a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.commentinheritance.md +++ b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.commentinheritance.md @@ -7,6 +7,10 @@
+## This package is not the recommended entry point to using this client library! + + For this library, we recommend using [com.microsoft.samples.google.v1](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/0.18.0/com.microsoft.samples.google.v1) for new applications. + ## Classes @@ -15,22 +19,22 @@ Class - + - + - + - + @@ -44,27 +48,27 @@ Interface - + - + - + - + - + diff --git a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.md b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.md index 6473498e..1d26ee71 100644 --- a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.md +++ b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.md @@ -7,6 +7,10 @@
Description
com.microsoft.samples.commentinheritance.Animalcom.microsoft.samples.commentinheritance.Animal Animal.
com.microsoft.samples.commentinheritance.Dogcom.microsoft.samples.commentinheritance.Dog Canine and man's best friend.
com.microsoft.samples.commentinheritance.Herbivorous.Plantcom.microsoft.samples.commentinheritance.Herbivorous.Plant
com.microsoft.samples.commentinheritance.Mammalcom.microsoft.samples.commentinheritance.Mammal Mammal.
Description
com.microsoft.samples.commentinheritance.Carnivorouscom.microsoft.samples.commentinheritance.Carnivorous Marks an Animal that eats other animals.
com.microsoft.samples.commentinheritance.Herbivorouscom.microsoft.samples.commentinheritance.Herbivorous Marks animals that eat plants.
com.microsoft.samples.commentinheritance.Omnivorouscom.microsoft.samples.commentinheritance.Omnivorous Eats plants and animals.
com.microsoft.samples.commentinheritance.Organismcom.microsoft.samples.commentinheritance.Organism
com.microsoft.samples.commentinheritance.Viviparouscom.microsoft.samples.commentinheritance.Viviparous Mammals that give birth to young that develop within the mother's body.
+## This package is not the recommended entry point to using this client library! + + For this library, we recommend using [com.microsoft.samples.google.v1](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/0.18.0/com.microsoft.samples.google.v1) for new applications. + ## Client Classes Client classes are the main entry point to using a package. They contain several variations of Java methods for each of the API's methods. @@ -17,7 +21,7 @@ Client Description -com.microsoft.samples.google.SpeechClient +com.microsoft.samples.google.SpeechClient Service Description: Service that implements Google Cloud Speech API. @@ -35,7 +39,7 @@ Settings Description -com.microsoft.samples.google.ProductSearchSettings +com.microsoft.samples.google.ProductSearchSettings Settings class to configure an instance of ProductSearchClient. @@ -43,7 +47,7 @@ Settings class to configure an instance of -com.microsoft.samples.google.SpeechSettings +com.microsoft.samples.google.SpeechSettings Settings class to configure an instance of SpeechClient. @@ -60,12 +64,12 @@ Class Description -com.microsoft.samples.google.ProductSearchSettings.Builder +com.microsoft.samples.google.ProductSearchSettings.Builder Builder for ProductSearchSettings. -com.microsoft.samples.google.RecognitionAudio +com.microsoft.samples.google.RecognitionAudio Contains audio data in the encoding specified in the RecognitionConfig. @@ -73,7 +77,7 @@ Builder for ProductSearchSettings. returns google.rpc.Code.INVALID_ARGUMENT. See -com.microsoft.samples.google.SpeechSettings.Builder +com.microsoft.samples.google.SpeechSettings.Builder Builder for SpeechSettings. @@ -87,7 +91,7 @@ Interface Description -com.microsoft.samples.google.BetaApi +com.microsoft.samples.google.BetaApi Indicates a public API that can change at any time, and has no guarantee of API stability and backward-compatibility. @@ -95,7 +99,7 @@ Indicates a public API that can change at any time, and has no guarantee of API

Usage guidelines: -com.microsoft.samples.google.ValidationException.Supplier +com.microsoft.samples.google.ValidationException.Supplier @@ -109,7 +113,7 @@ Enum Description -com.microsoft.samples.google.RecognitionAudio.AudioSourceCase +com.microsoft.samples.google.RecognitionAudio.AudioSourceCase @@ -123,7 +127,7 @@ Exception Description -com.microsoft.samples.google.ValidationException +com.microsoft.samples.google.ValidationException Exception thrown if there is a validation problem with a path template, http config, or related framework methods. Comes as an illegal argument exception subclass. Allows to globally set a diff --git a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1.md b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1.md index 7ad4133c..cb50fddf 100644 --- a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1.md +++ b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1.md @@ -17,7 +17,7 @@ Client Description -com.microsoft.samples.google.v1.SpeechClient +com.microsoft.samples.google.v1.SpeechClient Service Description: Service that implements Google Cloud Speech API. diff --git a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1.stub.md b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1.stub.md index b6943d51..f6f5094c 100644 --- a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1.stub.md +++ b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1.stub.md @@ -7,10 +7,14 @@ +## This package is not the recommended entry point to using this client library! + + For this library, we recommend using [com.microsoft.samples.google.v1](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/0.18.0/com.microsoft.samples.google.v1) for new applications. + ## Stub Package Implications This package is a a base stub class. It is for advanced usage and reflects the underlying API directly. -We generally recommend using non-stub, latest GA package, such as [com.microsoft.samples.google.v1](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/latest/com.microsoft.samples.google.v1). Use with caution. +We generally recommend using the non-stub, latest GA package, such as [com.microsoft.samples.google.v1](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/0.18.0/com.microsoft.samples.google.v1). Use with caution. ## Stub Classes @@ -19,21 +23,21 @@ Stub - + - + - + - + - + diff --git a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1beta.md b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1beta.md index 0219eb2b..96676b5a 100644 --- a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1beta.md +++ b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1beta.md @@ -7,18 +7,16 @@
Description
com.microsoft.samples.google.v1.stub.GrpcSpeechStubcom.microsoft.samples.google.v1.stub.GrpcSpeechStub gRPC stub implementation for the Speech service API.

This class is for advanced usage and reflects the underlying API directly.
com.microsoft.samples.google.v1.stub.HttpJsonSpeechStubcom.microsoft.samples.google.v1.stub.HttpJsonSpeechStub REST stub implementation for the Speech service API.

This class is for advanced usage and reflects the underlying API directly.
com.microsoft.samples.google.v1.stub.SpeechStubcom.microsoft.samples.google.v1.stub.SpeechStub Base stub class for the Speech service API. @@ -50,7 +54,7 @@ Settings Description
com.microsoft.samples.google.v1.stub.SpeechStubSettingscom.microsoft.samples.google.v1.stub.SpeechStubSettings Settings class to configure an instance of com.google.cloud.speech.v1p1beta1.stub.SpeechStub. @@ -67,7 +71,7 @@ Class Description
com.microsoft.samples.google.v1.stub.SpeechStubSettings.Buildercom.microsoft.samples.google.v1.stub.SpeechStubSettings.Builder Builder for SpeechStubSettings.
-## This package is not the latest GA version! +## This package is not the recommended entry point to using this client library! - For this library, we recommend using the [package](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/latest/com.microsoft.samples.google.v1) associated with API version v1 for new applications. + For this library, we recommend using [com.microsoft.samples.google.v1](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/0.18.0/com.microsoft.samples.google.v1) for new applications. ## Prerelease Implications This package is a prerelease version! Use with caution. -Prerelease versions are considered unstable as they may be shut down. You can read more about [Cloud API versioning strategy here](https://cloud.google.com/apis/design/versioning). -Each Cloud Java client library may contain multiple packages. Each package containing a version number in its name corresponds to a published version of the service. -We recommend using the latest stable version for new production applications, which can be identified by the largest numeric version that does not contain a suffix. -For example, if a client library has two packages: `v1` and `v2alpha`, then the latest stable version is `v1`. -If you use an unstable release, breaking changes may be introduced when upgrading. + +Prerelease versions are considered unstable as they may be shut down and/or subject to breaking changes when upgrading. +Use them only for testing or if you specifically need their experimental features. ## Client Classes Client classes are the main entry point to using a package. @@ -30,7 +28,7 @@ Client Description -com.microsoft.samples.google.v1beta.SpeechClient +com.microsoft.samples.google.v1beta.SpeechClient Service Description: Service that implements Google Cloud Speech API. diff --git a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1p1alpha.md b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1p1alpha.md index d019536d..0001294b 100644 --- a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1p1alpha.md +++ b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.google.v1p1alpha.md @@ -7,18 +7,16 @@ -## This package is not the latest GA version! +## This package is not the recommended entry point to using this client library! - For this library, we recommend using the [package](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/latest/com.microsoft.samples.google.v1) associated with API version v1 for new applications. + For this library, we recommend using [com.microsoft.samples.google.v1](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/0.18.0/com.microsoft.samples.google.v1) for new applications. ## Prerelease Implications This package is a prerelease version! Use with caution. -Prerelease versions are considered unstable as they may be shut down. You can read more about [Cloud API versioning strategy here](https://cloud.google.com/apis/design/versioning). -Each Cloud Java client library may contain multiple packages. Each package containing a version number in its name corresponds to a published version of the service. -We recommend using the latest stable version for new production applications, which can be identified by the largest numeric version that does not contain a suffix. -For example, if a client library has two packages: `v1` and `v2alpha`, then the latest stable version is `v1`. -If you use an unstable release, breaking changes may be introduced when upgrading. + +Prerelease versions are considered unstable as they may be shut down and/or subject to breaking changes when upgrading. +Use them only for testing or if you specifically need their experimental features. ## Client Classes Client classes are the main entry point to using a package. @@ -30,7 +28,7 @@ Client Description -com.microsoft.samples.google.v1p1alpha.SpeechClient +com.microsoft.samples.google.v1p1alpha.SpeechClient Service Description: Service that implements Google Cloud Speech API. diff --git a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.md b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.md index f3e3e013..0b3bab6e 100644 --- a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.md +++ b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.md @@ -7,6 +7,10 @@ +## This package is not the recommended entry point to using this client library! + + For this library, we recommend using [com.microsoft.samples.google.v1](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/0.18.0/com.microsoft.samples.google.v1) for new applications. + ## Classes @@ -15,43 +19,43 @@ Class - + - + - + - + - + - + - + - + @@ -65,12 +69,12 @@ Interface - + - + - + diff --git a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.offers.md b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.offers.md index a0183f03..8280fce5 100644 --- a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.offers.md +++ b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.offers.md @@ -7,6 +7,10 @@
Description
com.microsoft.samples.BasePartnerComponentcom.microsoft.samples.BasePartnerComponent Holds common partner component properties and behavior. All components should inherit from this class. The context object type.
com.microsoft.samples.BasePartnerComponentStringcom.microsoft.samples.BasePartnerComponentString Holds common partner component properties and behavior. The context is string type by default.
com.microsoft.samples.ExceptionHandlercom.microsoft.samples.ExceptionHandler Exception retry algorithm implementation used by RetryHelper.
com.microsoft.samples.ExceptionHandler.Buildercom.microsoft.samples.ExceptionHandler.Builder ExceptionHandler builder.
com.microsoft.samples.KeyValuePaircom.microsoft.samples.KeyValuePair
com.microsoft.samples.Linkcom.microsoft.samples.Link
com.microsoft.samples.Subpackagecom.microsoft.samples.Subpackage
com.microsoft.samples.SuperHerocom.microsoft.samples.SuperHero Hero is the main entity we will be using to something
Description
com.microsoft.samples.ExceptionHandler.Interceptorcom.microsoft.samples.ExceptionHandler.Interceptor
com.microsoft.samples.IPartnercom.microsoft.samples.IPartner The main entry point into using the partner SDK functionality. Represents a partner and encapsulates all the behavior attached to partners. Use this interface to get to the partner's @@ -86,7 +90,7 @@ Enum Description
com.microsoft.samples.ExceptionHandler.Interceptor.RetryResultcom.microsoft.samples.ExceptionHandler.Interceptor.RetryResult
+## This package is not the recommended entry point to using this client library! + + For this library, we recommend using [com.microsoft.samples.google.v1](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/0.18.0/com.microsoft.samples.google.v1) for new applications. + ## Classes @@ -15,7 +19,7 @@ Class - + diff --git a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.subpackage.md b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.subpackage.md index 376e932a..fb830aee 100644 --- a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.subpackage.md +++ b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/com.microsoft.samples.subpackage.md @@ -7,6 +7,10 @@
Description
com.microsoft.samples.offers.Offercom.microsoft.samples.offers.Offer Represents a form of product availability to customer
+## This package is not the recommended entry point to using this client library! + + For this library, we recommend using [com.microsoft.samples.google.v1](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/0.18.0/com.microsoft.samples.google.v1) for new applications. + ## Classes @@ -15,7 +19,7 @@ Class - + - + - + @@ -42,7 +46,7 @@ Interface - + - + @@ -72,7 +76,7 @@ Exception - + diff --git a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/overview.md b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/overview.md index 9ae046d5..df45ffd4 100644 --- a/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/overview.md +++ b/third_party/docfx-doclet-143274/src/test/resources/expected-generated-files/overview.md @@ -87,12 +87,26 @@ To use the latest version of this library, add this to your dependencies: libraryDependencies += "com.google.cloud" % "google-cloud-apikeys" % "0.18.0" -## Which version should I use? -For this library, we recommend using API version v1 for new applications. - -Each Cloud Java client library may contain multiple packages. Each package containing a version number in its name corresponds to a published version of the service. -We recommend using the latest stable version for new production applications, which can be identified by the largest numeric version that does not contain a suffix. -For example, if a client library has two packages: `v1` and `v2alpha`, then the latest stable version is `v1`. -If you use an unstable release, breaking changes may be introduced when upgrading. -You can read more about [Cloud API versioning strategy here](https://cloud.google.com/apis/design/versioning). +## Which version ID should I get started with? +For this library, we recommend using [com.microsoft.samples.google.v1](https://cloud.google.com/java/docs/reference/google-cloud-apikeys/0.18.0/com.microsoft.samples.google.v1) for new applications. + +### Understanding Version ID and Library Versions +When using a Cloud client library, it's important to distinguish between two types of versions: +- **Library Version**: The version of the software package (the client library) that helps you interact with the Cloud service. These libraries are +released and updated frequently with bug fixes, improvements, and support for new service features and versions. The version selector at +the top of this page represents the client library version. +- **Version ID**: The version of the Cloud service itself (e.g. API Keys API). New Version IDs are introduced infrequently, and often involve +changes to the core functionality and structure of the Cloud service itself. The packages in the lefthand navigation represent packages tied +to a specific Version ID of the Cloud service. + +### Managing Library Versions +We recommend using the com.google.cloud:libraries-bom installation method detailed above to streamline dependency management +across multiple Cloud Java client libraries. This ensures compatibility and simplifies updates. + +### Choosing the Right Version ID +Each Cloud Java client library may contain packages tied to specific Version IDs (e.g., v1, v2alpha). For new production applications, use +the latest stable Version ID. This is identified by the highest version number **without** a suffix (like "alpha" or "beta"). You can read more about +[Cloud API versioning strategy here](https://cloud.google.com/apis/design/versioning). + +**Important**: Unstable Version ID releases (those _with_ suffixes) are subject to breaking changes when upgrading. Use them only for testing or if you specifically need their experimental features.
Description
com.microsoft.samples.subpackage.Personcom.microsoft.samples.subpackage.Person Class that describes some person @@ -23,12 +27,12 @@ Class that describes some person
com.microsoft.samples.subpackage.Person.IdentificationInfocom.microsoft.samples.subpackage.Person.IdentificationInfo Class that describes person's identification
com.microsoft.samples.subpackage.Tuplecom.microsoft.samples.subpackage.Tuple
Description
com.microsoft.samples.subpackage.Displaycom.microsoft.samples.subpackage.Display Do you see some First code block? @@ -58,7 +62,7 @@ Enum Description
com.microsoft.samples.subpackage.Person.IdentificationInfo.Gendercom.microsoft.samples.subpackage.Person.IdentificationInfo.Gender Enum describes person's gender
Description
com.microsoft.samples.subpackage.CustomExceptioncom.microsoft.samples.subpackage.CustomException