CheckStyleRule-Javadoc-Codesnippet Batch#3, No.7 and No.8

eng/code-quality-reports/src/main/java/com/azure/tools/checkstyle/checks/JavadocCodeSnippetCheck.java

@@ -0,0 +1,206 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.tools.checkstyle.checks;
+
+import com.puppycrawl.tools.checkstyle.api.DetailNode;
+import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
+import com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck;
+import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.regex.Pattern;
+
+/**
+ * Requirement of Javadoc annotation {@literal @codesnippet}  check:
+ * <ol>
+ *   <li>Use {@literal {@codesnippet ...}} instead of '<code>', '<pre>', or {@literal {@code ...}) if these tags span
+ *       multiple lines. Inline code sample are fine as-is</li>
+ *   <ol>Naming pattern of {@literal {@codesnippet}}:
+ *     <li>For package name, class name, they should all be lower case;
+ *         For method name, the first letter of method name should be lower case;
+ *         For parameters, they should only be letters. Concatenate all parameters with dash character.</li>
+ *     <li>Jonathan will add more requirement specs later.</li>
+ *   </ol>
+ * </ol>
+ */
+public class JavadocCodeSnippetCheck extends AbstractJavadocCheck {
+    // Code snippet annotation naming pattern:
+    // Check package name, class name, method name, parameters names' naming patterns.
+    private static final String CLASS_PATH_REGEX = "[a-z.]+";
+    private static final String METHOD_NAME_REGEX = "^[a-z][a-zA-Z]+";
+    private static final String PARAMETERS_REGEX = "[a-zA-Z-]+";
+
+    private static final String CODE_SNIPPET_ANNOTATION = "@codesnippet";
+    private static final String MULTIPLE_LINE_SPAN_ERROR = "Tag '%s' span in multiple lines. Use @codesnippet annotation" +
+        " instead of '%s' to ensure that the code block always compiles.";
+
+    // HTML tag set that need to be checked to see if there tags span on multiple lines.
+    private static final Set<String> CHECK_TAGS = Collections.unmodifiableSet(new HashSet<>(
+        Arrays.asList("pre", "code")));
+
+    @Override
+    public int[] getDefaultJavadocTokens() {
+        return getRequiredJavadocTokens();
+    }
+
+    @Override
+    public int[] getRequiredJavadocTokens() {
+        return new int[] {
+            JavadocTokenTypes.HTML_ELEMENT_START,
+            JavadocTokenTypes.JAVADOC_INLINE_TAG
+        };
+    }
+
+    @Override
+    public void visitJavadocToken(DetailNode token) {
+        switch (token.getType()) {
+            case JavadocTokenTypes.HTML_ELEMENT_START:
+                checkHtmlElementStart(token);
+                break;
+            case JavadocTokenTypes.JAVADOC_INLINE_TAG:
+                checkJavadocInlineTag(token);
+                checkCodeSnippetNaming(token);
+            default:
+                // Checkstyle complains if there's no default block in switch
+                break;
+        }
+    }
+
+    /**
+     * Use {@literal {@codesnippet ...}} instead of '<code>', '<pre>', or {@literal {@code ...}) if these tags span
+     * multiple lines. Inline code sample are fine as-is.
+     *
+     * @param htmlElementStartNode HTML_ELEMENT_START node
+     */
+    private void checkHtmlElementStart(DetailNode htmlElementStartNode) {
+        final DetailNode tagNameNode = JavadocUtil.findFirstToken(htmlElementStartNode, JavadocTokenTypes.HTML_TAG_NAME);
+        // HTML tags are case-insensitive
+        final String tagName = tagNameNode.getText().toLowerCase();
+        if (!CHECK_TAGS.contains(tagName)) {
+            return;
+        }
+
+        final String tagNameBracket = "<" + tagName + ">";
+        final DetailNode htmlTagNode = htmlElementStartNode.getParent();
+
+        for (final DetailNode child : htmlTagNode.getChildren()) {
+            final int childType = child.getType();
+            if (childType == JavadocTokenTypes.NEWLINE || childType == JavadocTokenTypes.LEADING_ASTERISK) {
+                log(child.getLineNumber(), child.getColumnNumber(),
+                    String.format(MULTIPLE_LINE_SPAN_ERROR, tagNameBracket, tagNameBracket));
+                return;
+            }
+        }
+    }
+
+    /**
+     * Check to see if the JAVADOC_INLINE_TAG node is {@literal @code} tag. If it is, check if the tag contains a new line
+     * or a leading asterisk, which implies the tag has spanned in multiple lines.
+     *
+     * @param inlineTagNode JAVADOC_INLINE_TAG javadoc node
+     */
+    private void checkJavadocInlineTag(DetailNode inlineTagNode) {
+        final DetailNode codeLiteralNode = JavadocUtil.findFirstToken(inlineTagNode, JavadocTokenTypes.CODE_LITERAL);
+        if (codeLiteralNode == null) {
+            return;
+        }
+
+        final String codeLiteral = codeLiteralNode.getText();
+
+        for (final DetailNode child : inlineTagNode.getChildren()) {
+            final int childType = child.getType();
+            if (childType == JavadocTokenTypes.NEWLINE || childType == JavadocTokenTypes.LEADING_ASTERISK) {
+                log(child.getLineNumber(), child.getColumnNumber(),
+                    String.format(MULTIPLE_LINE_SPAN_ERROR, codeLiteral, codeLiteral));
+                return;
+            }
+        }
+    }
+
+    /**
+     * Check to see if the code snippet name matched the naming pattern.
+     * A valid example of naming pattern could be:
+     *   com.azure.security.keyvault.keys.cryptography.cryptographyclient.encrypt#symmetric-encrypt
+     *
+     * For more detail, please refers to this class description javadoc.
+     *
+     * @param inlineTagNode JAVADOC_INLINE_TAG javadoc node
+     */
+    private void checkCodeSnippetNaming(DetailNode inlineTagNode) {
+        // Only checks on @codesnippet annotation
+        final DetailNode customNameNode = JavadocUtil.findFirstToken(inlineTagNode, JavadocTokenTypes.CUSTOM_NAME);
+        if (customNameNode == null || !CODE_SNIPPET_ANNOTATION.equals(customNameNode.getText())) {
+            return;
+        }
+
+        final DetailNode descriptionNode = JavadocUtil.findFirstToken(inlineTagNode, JavadocTokenTypes.DESCRIPTION);
+        if (descriptionNode == null) {
+            log(descriptionNode.getLineNumber(), descriptionNode.getColumnNumber(),
+                String.format("%s has no description.", CODE_SNIPPET_ANNOTATION));
+            return;
+        }
+        // DESCRIPTION always has child TEXT
+        final DetailNode textNode = JavadocUtil.findFirstToken(descriptionNode, JavadocTokenTypes.TEXT);
+        final String namingPattern = textNode.getText();
+        // Verify naming pattern spec:
+        // 1. For package name, class name, they should all be lower case;
+        //    For method name,  the first letter of method name should be lower case.
+        //    For parameters, they should only be letters. Concatenate all parameters with dash character
+        // 2. Jonathon will add more requirement specs later
+        if (!isNamingMatch(namingPattern)) {
+            log(textNode.getLineNumber(), textNode.getColumnNumber(),
+                String.format("Naming pattern mismatch. It should only contain lower case for the package path and class name for matching regular expression ''%s''" +
+                    " and the first letter of method name must be small case for matching regular expression ''%s'', and the parameters should be all small case for matching " +
+                    "regular expression ''%s''.", CLASS_PATH_REGEX, METHOD_NAME_REGEX, PARAMETERS_REGEX));
+        }
+    }
+
+    /**
+     *  Find if the given name of code snippet matched the naming pattern specs.
+     *
+     * @param name code snippet name
+     * @return true if match, otherwise, false
+     */
+    private boolean isNamingMatch(String name) {
+        final String[] str = name.split("#");
+
+        // invalid naming pattern
+        if (str.length == 0 || str.length > 2) {
+            return false;
+        }
+
+        final String classPath = str[0];
+        // corner case: empty string will also be false
+        if (classPath.isEmpty()) {
+            return false;
+        }
+
+        final int lastIndexOf = classPath.lastIndexOf(".");
+        if (lastIndexOf == -1) {
+            return false;
+        }
+
+        // full path of the class, check to see if there path only has lower case letters and dot
+        final String className = classPath.substring(0, lastIndexOf);
+        if (!Pattern.compile(CLASS_PATH_REGEX).matcher(className).matches()) {
+            return false;
+        }
+
+        // method name
+        final String methodName = classPath.substring(lastIndexOf + 1);
+        if (!Pattern.compile(METHOD_NAME_REGEX).matcher(methodName).matches()) {
+            return false;
+        }
+
+        // parameters of method function
+        if (str.length == 2 && !Pattern.compile(PARAMETERS_REGEX).matcher(str[1]).matches()) {
+            return false;
+        }
+
+        return true;
+    }
+}

eng/code-quality-reports/src/main/resources/checkstyle/checkstyle.xml

@@ -276,33 +276,33 @@ page at http://checkstyle.sourceforge.net/config.html -->
     -->
     <module name="com.azure.tools.checkstyle.checks.ServiceClientChecks"/>
 
-    <!--CUSTOM CHECKS-->
+    <!-- CUSTOM CHECKS -->
     <!--Checks for the public API that should
     1) not return classes in the implementation package
     2) no class of implementation package as method's parameters -->
     <module name="com.azure.tools.checkstyle.checks.NoImplInPublicAPI"/>
 
-    <!--CUSTOM CHECKS-->
+    <!-- CUSTOM CHECKS -->
     <!-- Verify the classes with annotation @ServiceClient should have following rules:
     1) No public or protected constructors
     2) No public static method named 'builder'
     3) Since these classes are supposed to be immutable, all fields in the service client classes should be final -->
     <module name="com.azure.tools.checkstyle.checks.ServiceClientInstantiationCheck"/>
 
-    <!--CUSTOM CHECKS-->
+    <!-- CUSTOM CHECKS -->
     <!-- Checks for no external dependency exposed in the public API.
     We should only return types, and accept argument types, that are from the com.azure namespace.
     All other types should have suppression added if required. -->
     <module name="com.azure.tools.checkstyle.checks.ExternalDependencyExposedCheck"/>
 
-    <!--CUSTOM CHECKS-->
+    <!-- CUSTOM CHECKS -->
     <!-- The @ServiceClientBuilder class should have the following rules:
     1) All service client builder should be named <ServiceName>ClientBuilder and annotated with @ServiceClientBuilder.
     2) Has a method 'buildClient()' to build a synchronous client,
     3) Has a method 'buildAsyncClient()' to build an asynchronous client -->
     <module name="com.azure.tools.checkstyle.checks.ServiceClientBuilderCheck"/>
 
-    <!--CUSTOM CHECKS-->
+    <!-- CUSTOM CHECKS -->
     <!-- The @ServiceInterface class should have the following rules:
     1) The annotation property 'name' should be non-empty
     2) The length of value of property 'name' should be less than 20 characters and without space -->
@@ -316,5 +316,16 @@ page at http://checkstyle.sourceforge.net/config.html -->
     <!--CUSTOM CHECKS-->
     <!-- Must use 'logger.logAndThrow' but not directly calling 'throw exception' -->
 <!--    <module name="com.azure.tools.checkstyle.checks.ThrownClientLoggerCheck"/>-->
+
+    <!-- CUSTOM CHECKS -->
+    <!-- Requirement of Javadoc annotation @codesnippet check:
+      1) Use {@codesnippet ...} instead of '<code>', '<pre>', or '{@code ...}' if these tags span multiple lines.
+         Inline code sample are fine as-is.
+      2) naming pattern of @codesnippet:
+          a) For package name, class name, they should all be lower case.
+             For method name,  the first letter of method name should be lower case.
+             For parameters, they should only be letters. Concatenate all parameters with dash character.
+          b) Jonathon will add more requirement specs later. -->
+    <module name="com.azure.tools.checkstyle.checks.JavadocCodeSnippetCheck"/>
   </module>
 </module>

sdk/identity/azure-identity/src/main/java/com/azure/identity/credential/AadCredentialBuilderBase.java

@@ -13,7 +13,7 @@ public abstract class AadCredentialBuilderBase<T extends AadCredentialBuilderBas
     /**
      * Specifies the Azure Active Directory endpoint to acquire tokens.
      * @param authorityHost the Azure Active Directory endpoint
-     * @return {@link <T>} itself
+     * @return {@code <T>} itself
      */
     @SuppressWarnings("unchecked")
     public T authorityHost(String authorityHost) {
@@ -24,7 +24,7 @@ public T authorityHost(String authorityHost) {
     /**
      * Sets the client ID of the application.
      * @param clientId the client ID of the application.
-     * @return {@link <T>} itself
+     * @return {@code <T>} itself
      */
     @SuppressWarnings("unchecked")
     public T clientId(String clientId) {

sdk/identity/azure-identity/src/main/java/com/azure/identity/credential/CredentialBuilderBase.java

@@ -22,7 +22,7 @@ public abstract class CredentialBuilderBase<T extends CredentialBuilderBase<T>>
     /**
      * Specifies the max number of retries when an authentication request fails.
      * @param maxRetry the number of retries
-     * @return {@link <T>} itself
+     * @return {@code <T>} itself
      */
     @SuppressWarnings("unchecked")
     public T maxRetry(int maxRetry) {
@@ -33,7 +33,7 @@ public T maxRetry(int maxRetry) {
     /**
      * Specifies a Function to calculate seconds of timeout on every retried request.
      * @param retryTimeout the Function that returns a timeout in seconds given the number of retry
-     * @return {@link <T>} itself
+     * @return {@code <T>} itself
      */
     @SuppressWarnings("unchecked")
     public T retryTimeout(Function<Integer, Integer> retryTimeout) {
@@ -44,7 +44,7 @@ public T retryTimeout(Function<Integer, Integer> retryTimeout) {
     /**
      * Specifies he options for proxy configuration.
      * @param proxyOptions the options for proxy configuration
-     * @return {@link <T>} itself
+     * @return {@code <T>} itself
      */
     @SuppressWarnings("unchecked")
     public T proxyOptions(ProxyOptions proxyOptions) {