Azure · alzimmermsft · Oct 6, 2021 · Oct 4, 2021 · Oct 4, 2021 · Oct 4, 2021
@@ -18,6 +18,7 @@
   <suppress checks="MissingJavadocMethod" files=".*[/\\]samples[/\\].*\.java"/>
   <suppress checks="MissingJavadocType" files=".*[/\\]samples[/\\].*\.java"/>
   <suppress checks="MissingJavadocPackage" files=".*[/\\]samples[/\\].*\.java"/>
+  <suppress checks="MissingJavadocPackage" files=".*[/\\]samples[/\\].*\.java"/>
 
   <!-- Code was taken from Netty and uses its license instead of our usual one. -->
   <suppress checks="Header" files="com.azure.core.http.netty.implementation.HttpProxyHandler"/>
@@ -547,7 +548,7 @@ the main ServiceBusClientBuilder. -->
   <!-- The clients don't end with 'Client' but instead with 'Sender' -->
   <suppress checks="com.azure.tools.checkstyle.checks.ServiceClientBuilderCheck"
             files="com.azure.search.documents.SearchClientBuilder"
-            lines="376,408,420"/>
+            lines="392,424,436"/>
   <suppress checks="com.azure.tools.checkstyle.checks.ServiceClientCheck"
             files="com.azure.search.documents.SearchIndexingBufferedAsyncSender"/>
   <suppress checks="com.azure.tools.checkstyle.checks.ServiceClientCheck"
@@ -612,7 +613,7 @@ the main ServiceBusClientBuilder. -->
   <!-- Checkstyle suppressions to keep HttpPipelinePolicy in implementation folder. -->
   <suppress checks="com.azure.tools.checkstyle.checks.HttpPipelinePolicyCheck"
             files="com.azure.communication.callingserver.implementation.RedirectPolicy.java"/>
-            
+
   <!-- Suppress VisibilityModifier in MemberConverterImplTests.-->
   <suppress checks="VisibilityModifier"
             files="com.azure.core.implementation.jackson.MemberNameConverterImplTests.java"/>

@@ -40,13 +40,23 @@ def generate_overview(readme_file, version, overview_file_path):
 
     if (readme_exists):
         with open(readme_file, 'r', encoding='utf-8') as f:
-            readme_content = f.read()
+            raw_readme_content_lines = f.readlines()
+
+        # Before passing the README contents to markdown2 clean out the codesnippet tags on the java code fences.
+        # Clean ```java com.azure.core.aCodeSnippetTag to ```java, without doing this markdown2 won't properly process
+        # the contents of the code fence.
+        cleaned_readme_content_lines = []
+        for line in raw_readme_content_lines:
+            cleaned_readme_content_lines.append(re.sub(pattern="``` *java +[a-zA-Z0-9.#\-_]*", repl="```java", string=line, flags=re.UNICODE))
+
+        readme_content = ''.join(cleaned_readme_content_lines)
+
         # markdown2.markdown will create html from the readme.md file. The fenced-code-blocks
         # extras being passed into the markdown call is necessary to deal with the embedded
         # code blocks within the readme so they'll displaye correctly in the html
         # The target-blank-links will open new tab for new page, but leave the anchor link in the same page.
         # The toc helps the anchor link to jump to the right place.
-        html_readme_content = markdown2.markdown(re.sub(pattern='@', repl='{@literal @}', string=readme_content, flags=re.MULTILINE), extras=["fenced-code-blocks", "target-blank-links", "toc"])
+        html_readme_content = markdown2.markdown(re.sub(pattern='(?<!opencode)@', repl='{@literal @}', string=readme_content, flags=re.MULTILINE|re.UNICODE), extras=["fenced-code-blocks", "target-blank-links", "toc"])
 
         # Now use BeautifulSoup to cleanup the generated HTML so that it conforms to Javadoc compliance.
         soup = BeautifulSoup(html_readme_content, features="html.parser")

@@ -270,7 +270,7 @@ org.revapi:revapi-java;0.20.0
 org.revapi:revapi-maven-plugin;0.11.2
 org.moditect:moditect-maven-plugin;1.0.0.RC1
 org.ow2.asm:asm;9.1
-com.azure.tools:codesnippet-maven-plugin;1.0.0-beta.1
+com.azure.tools:codesnippet-maven-plugin;1.0.0-beta.2
 
 # External Dependency Exceptions
 # This section is for external dependencies whose versions were different than

@@ -39,7 +39,7 @@ A span represents a single operation in a trace. A span could be representative
 
 ## Examples
 
-The following sections provides examples of using the azure-core-tracing-opentelemetry plugin with some of the Azure Java SDK libraries:
+The following sections provides examples of using the azure-core-tracing-opentelemetry plugin with a few Azure Java SDK libraries:
 
 ### Using the plugin package with HTTP client libraries
 
@@ -49,35 +49,35 @@ The following sections provides examples of using the azure-core-tracing-opentel
     The plugin package creates a root span to encapsulate all the child spans created in the calling methods when no parent span is passed in the context.
     This [sample][sample_key_vault] provides an example when no user parent span is passed.
 
-    ```java
-    // Get the Tracer Provider
-    static TracerSdkProvider tracerProvider = OpenTelemetrySdk.getTracerProvider();
-    private static final Tracer TRACER = configureOpenTelemetryAndLoggingExporter();
+```java
+// Get the Tracer Provider
+static TracerSdkProvider tracerProvider = OpenTelemetrySdk.getTracerProvider();
+private static final Tracer TRACER = configureOpenTelemetryAndLoggingExporter();
 
-    public static void main(String[] args) {
-       doClientWork();
-    }
+public static void main(String[] args) {
+   doClientWork();
+}
 
-    public static void doClientWork() {
-       SecretClient client = new SecretClientBuilder()
-         .endpoint("<your-vault-url>")
-         .credential(new DefaultAzureCredentialBuilder().build())
-         .buildClient();
+public static void doClientWork() {
+   SecretClient client = new SecretClientBuilder()
+     .endpoint("<your-vault-url>")
+     .credential(new DefaultAzureCredentialBuilder().build())
+     .buildClient();
 
-       Span span = TRACER.spanBuilder("user-parent-span").startSpan();
-       try (Scope scope = TRACER.withSpan(span)) {
+   Span span = TRACER.spanBuilder("user-parent-span").startSpan();
+   try (Scope scope = TRACER.withSpan(span)) {
 
-           // Thread bound (sync) calls will automatically pick up the parent span and you don't need to pass it explicitly.
-           secretClient.setSecret(new Secret("secret_name", "secret_value));
+       // Thread bound (sync) calls will automatically pick up the parent span and you don't need to pass it explicitly.
+       secretClient.setSecret(new Secret("secret_name", "secret_value));
 
-           // Optionally, to specify the context you can use
-           // final Context traceContext = new Context(PARENT_SPAN_KEY, span);
-           // secretClient.setSecretWithResponse(new Secret("secret_name", "secret_value", traceContext));
-       } finally {
-           span.end();
-       }
-    }
-    ```
+       // Optionally, to specify the context you can use
+       // final Context traceContext = new Context(PARENT_SPAN_KEY, span);
+       // secretClient.setSecretWithResponse(new Secret("secret_name", "secret_value", traceContext));
+   } finally {
+       span.end();
+   }
+}
+```
 
 ### Using the plugin package with AMQP client libraries
 

@@ -212,7 +212,7 @@
       <plugin>
         <groupId>com.azure.tools</groupId>
         <artifactId>codesnippet-maven-plugin</artifactId>
-        <version>1.0.0-beta.1</version> <!-- {x-version-update;com.azure.tools:codesnippet-maven-plugin;external_dependency} -->
+        <version>1.0.0-beta.2</version> <!-- {x-version-update;com.azure.tools:codesnippet-maven-plugin;external_dependency} -->
         <configuration>
           <skip>${skipNewCodesnippetTooling}</skip>
         </configuration>

@@ -128,8 +128,7 @@ The SDK provides three clients.
 To create a `SearchIndexClient/SearchIndexAsyncClient`, you will need the values of the Azure Cognitive Search service
 URL endpoint and admin key.
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L66-L69 -->
-```java
+```java readme-sample-createIndexClient
 SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
     .endpoint(endpoint)
     .credential(new AzureKeyCredential(apiKey))
@@ -138,8 +137,7 @@ SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
 
 or
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L73-L76 -->
-```java
+```java readme-sample-createIndexAsyncClient
 SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
     .endpoint(endpoint)
     .credential(new AzureKeyCredential(apiKey))
@@ -151,8 +149,7 @@ SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
 To create a `SearchIndexerClient/SearchIndexerAsyncClient`, you will need the values of the Azure Cognitive Search service
 URL endpoint and admin key.
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L80-L83 -->
-```java
+```java readme-sample-createIndexerClient
 SearchIndexerClient searchIndexerClient = new SearchIndexerClientBuilder()
     .endpoint(endpoint)
     .credential(new AzureKeyCredential(apiKey))
@@ -161,8 +158,7 @@ SearchIndexerClient searchIndexerClient = new SearchIndexerClientBuilder()
 
 or
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L87-L90 -->
-```java
+```java readme-sample-createIndexerAsyncClient
 SearchIndexerAsyncClient searchIndexerAsyncClient = new SearchIndexerClientBuilder()
     .endpoint(endpoint)
     .credential(new AzureKeyCredential(apiKey))
@@ -174,8 +170,7 @@ SearchIndexerAsyncClient searchIndexerAsyncClient = new SearchIndexerClientBuild
 Once you have the values of the Azure Cognitive Search service URL endpoint and
 admin key, you can create the `SearchClient/SearchAsyncClient` with an existing index name:
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L50-L54 -->
-```java
+```java readme-sample-createSearchClient
 SearchClient searchClient = new SearchClientBuilder()
     .endpoint(endpoint)
     .credential(new AzureKeyCredential(adminKey))
@@ -185,8 +180,7 @@ SearchClient searchClient = new SearchClientBuilder()
 
 or
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L58-L62 -->
-```java
+```java readme-sample-createAsyncSearchClient
 SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
     .endpoint(endpoint)
     .credential(new AzureKeyCredential(adminKey))
@@ -252,8 +246,7 @@ Let's explore them with a search for a "luxury" hotel.
 `SearchDocument` is the default type returned from queries when you don't provide your own.  Here we perform the search,
 enumerate over the results, and extract data using `SearchDocument`'s dictionary indexer.
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L122-L127 -->
-```java
+```java readme-sample-searchWithDynamicType
 for (SearchResult searchResult : searchClient.search("luxury")) {
     SearchDocument doc = searchResult.getDocument(SearchDocument.class);
     String id = (String) doc.get("hotelId");
@@ -266,8 +259,7 @@ for (SearchResult searchResult : searchClient.search("luxury")) {
 
 Define a `Hotel` class.
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L130-L151 -->
-```java
+```java readme-sample-hotelclass
 public class Hotel {
     private String id;
     private String name;
@@ -294,8 +286,7 @@ public class Hotel {
 
 Use it in place of `SearchDocument` when querying.
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L154-L159 -->
-```java
+```java readme-sample-searchWithStronglyType
 for (SearchResult searchResult : searchClient.search("luxury")) {
     Hotel doc = searchResult.getDocument(Hotel.class);
     String id = doc.getId();
@@ -312,8 +303,7 @@ The `SearchOptions` provide powerful control over the behavior of our queries.
 
 Let's search for the top 5 luxury hotels with a good rating.
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L163-L168 -->
-```java
+```java readme-sample-searchWithSearchOptions
 SearchOptions options = new SearchOptions()
     .setFilter("rating ge 4")
     .setOrderBy("rating desc")
@@ -332,16 +322,14 @@ There are multiple ways of preparing search fields for a search index. For basic
 `List<SearchField>`. There are three annotations `SimpleFieldProperty`, `SearchFieldProperty` and `FieldBuilderIgnore`
 to configure the field of model class.
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L242-L243 -->
-```java
+```java readme-sample-createIndexUseFieldBuilder
 List<SearchField> searchFields = SearchIndexClient.buildSearchFields(Hotel.class, null);
 searchIndexClient.createIndex(new SearchIndex("index", searchFields));
 ```
 
 For advanced scenarios, we can build search fields using `SearchField` directly.
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L192-L238 -->
-```java
+```java readme-sample-createIndex
 List<SearchField> searchFieldList = new ArrayList<>();
 searchFieldList.add(new SearchField("hotelId", SearchFieldDataType.STRING)
     .setKey(true)
@@ -397,8 +385,7 @@ In addition to querying for documents using keywords and optional filters, you c
 your index if you already know the key. You could get the key from a query, for example, and want to show more
 information about it or navigate your customer to that document.
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L180-L181 -->
-```java
+```java readme-sample-retrieveDocuments
 Hotel hotel = searchClient.getDocument("1", Hotel.class);
 System.out.printf("This is hotelId %s, and this is hotel name %s.%n", hotel.getId(), hotel.getName());
 ```
@@ -409,8 +396,7 @@ You can `Upload`, `Merge`, `MergeOrUpload`, and `Delete` multiple documents from
 There are [a few special rules for merging](https://docs.microsoft.com/rest/api/searchservice/addupdate-or-delete-documents#document-actions)
 to be aware of.
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L185-L188 -->
-```java
+```java readme-sample-batchDocumentsOperations
 IndexDocumentsBatch<Hotel> batch = new IndexDocumentsBatch<>();
 batch.addUploadActions(Collections.singletonList(new Hotel().setId("783").setName("Upload Inn")));
 batch.addMergeActions(Collections.singletonList(new Hotel().setId("12").setName("Renovated Ranch")));
@@ -426,8 +412,7 @@ to `false` to get a successful response with an `IndexDocumentsResult` for inspe
 The examples so far have been using synchronous APIs, but we provide full support for async APIs as well. You'll need
 to use [SearchAsyncClient](#create-a-searchclient).
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L172-L176 -->
-```java
+```java readme-sample-searchWithAsyncClient
 searchAsyncClient.search("luxury")
     .subscribe(result -> {
         Hotel hotel = result.getDocument(Hotel.class);
@@ -448,8 +433,7 @@ error if you try to retrieve a document that doesn't exist in your index.
 Any Search API operation that fails will throw an [`HttpResponseException`][HttpResponseException] with helpful
 [`Status codes`][status_codes]. Many of these errors are recoverable.
 
-<!-- embedme ./src/samples/java/com/azure/search/documents/ReadmeSamples.java#L110-L118 -->
-```java
+```java readme-sample-handleErrorsWithSyncClient
 try {
     Iterable<SearchResult> results = searchClient.search("hotel");
 } catch (HttpResponseException ex) {

@@ -40,6 +40,9 @@
       --add-reads com.azure.core.test=ALL-UNNAMED
       --add-reads com.azure.core.http.netty=ALL-UNNAMED
     </javaModulesSurefireArgLine>
+    <skipNewCodesnippetTooling>false</skipNewCodesnippetTooling>
+    <javadocDoclet></javadocDoclet>
+    <javadocDocletOptions></javadocDocletOptions>
   </properties>
 
   <dependencies>