feat: include support for @ see tags

third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/BuilderUtil.java

@@ -37,14 +37,6 @@ final class BuilderUtil {
     private static final Pattern XREF_LINK_RESOLVE_PATTERN = Pattern.compile("(?<class>\\w+)\\#(?<member>\\w+)(\\((?<param>.*)\\))?");
     public final static String[] LANGS = {"java"};
 
-    static String getDeprecatedSummary(String depMsg, String summary) {
-        String result = "<p>(deprecated) " + depMsg + "</p>";
-        if (summary != null && !summary.equals("")) {
-            result = result + "\n" + summary;
-        }
-        return result;
-    }
-
     static String populateUidValues(String text, LookupContext lookupContext) {
         if (StringUtils.isBlank(text)) {
             return text;
@@ -196,6 +188,7 @@ static <T extends Element> void populateItemFields(MetadataFileItem item, BaseLo
         item.setType(lookup.extractType(element));
         item.setJavaType(lookup.extractJavaType(element));
         item.setSummary(lookup.extractSummary(element));
+        item.setStatus(lookup.extractStatus(element));
         item.setContent(lookup.extractContent(element));
     }
 }

third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/ClassBuilder.java

@@ -35,7 +35,6 @@
 import java.util.stream.Collectors;
 
 import static com.microsoft.build.BuilderUtil.LANGS;
-import static com.microsoft.build.BuilderUtil.getDeprecatedSummary;
 import static com.microsoft.build.BuilderUtil.populateItemFields;
 
 class ClassBuilder {
@@ -97,11 +96,8 @@ private void addClassInfo(TypeElement classElement, MetadataFile classMetadataFi
         classItem.setInheritance(classLookup.extractSuperclass(classElement));
         classItem.setInterfaces(classLookup.extractInterfaces(classElement));
         classItem.setInheritedMethods(classLookup.extractInheritedMethods(classElement));
-        String depMsg = classLookup.extractDeprecatedDescription(classElement);
-        if (depMsg != null) {
-            classItem.setSummary(getDeprecatedSummary(depMsg, classItem.getSummary()));
-            classItem.setStatus(Status.DEPRECATED.toString());
-        }
+        classItem.setSummary(classLookup.extractSummary(classElement));
+        classItem.setStatus(classLookup.extractStatus(classElement));
         classMetadataFile.getItems().add(classItem);
     }
 
@@ -111,11 +107,6 @@ void addConstructorsInfo(TypeElement classElement, MetadataFile classMetadataFil
             constructorItem.setOverload(classItemsLookup.extractOverload(constructorElement));
             constructorItem.setContent(classItemsLookup.extractConstructorContent(constructorElement));
             constructorItem.setParameters(classItemsLookup.extractParameters(constructorElement));
-            String depMsg = classItemsLookup.extractDeprecatedDescription(constructorElement);
-            if (depMsg != null) {
-                constructorItem.setSummary(getDeprecatedSummary(depMsg, constructorItem.getSummary()));
-                constructorItem.setStatus(Status.DEPRECATED.toString());
-            }
             classMetadataFile.getItems().add(constructorItem);
 
             referenceBuilder.addParameterReferences(constructorItem, classMetadataFile);
@@ -134,11 +125,6 @@ private void addMethodsInfo(TypeElement classElement, MetadataFile classMetadata
                     methodItem.setParameters(classItemsLookup.extractParameters(methodElement));
                     methodItem.setReturn(classItemsLookup.extractReturn(methodElement));
                     methodItem.setOverridden(classItemsLookup.extractOverridden(methodElement));
-                    String depMsg = classItemsLookup.extractDeprecatedDescription(methodElement);
-                    if (depMsg != null) {
-                        methodItem.setSummary(getDeprecatedSummary(depMsg, methodItem.getSummary()));
-                        methodItem.setStatus(Status.DEPRECATED.toString());
-                    }
 
                     classMetadataFile.getItems().add(methodItem);
                     referenceBuilder.addExceptionReferences(methodItem, classMetadataFile);
@@ -155,12 +141,6 @@ private void addFieldsInfo(TypeElement classElement, MetadataFile classMetadataF
                     MetadataFileItem fieldItem = buildMetadataFileItem(fieldElement);
                     fieldItem.setContent(classItemsLookup.extractFieldContent(fieldElement));
                     fieldItem.setReturn(classItemsLookup.extractReturn(fieldElement));
-                    String depMsg = classItemsLookup.extractDeprecatedDescription(fieldElement);
-                    if (depMsg != null) {
-                        fieldItem.setSummary(getDeprecatedSummary(depMsg, fieldItem.getSummary()));
-                        fieldItem.setStatus(Status.DEPRECATED.toString());
-                    }
-
                     classMetadataFile.getItems().add(fieldItem);
                     referenceBuilder.addReturnReferences(fieldItem, classMetadataFile);
                 });
@@ -182,6 +162,7 @@ private MetadataFileItem buildMetadataFileItem(Element element) {
             setJavaType(classItemsLookup.extractJavaType(element));
             setPackageName(classItemsLookup.extractPackageName(element));
             setSummary(classItemsLookup.extractSummary(element));
+            setStatus(classItemsLookup.extractStatus(element));
         }};
     }
 

third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/YmlFilesBuilder.java

@@ -59,7 +59,7 @@ public boolean build() {
         for (PackageElement packageElement :
                 elementUtil.extractPackageElements(environment.getIncludedElements())) {
             String packageUid = packageLookup.extractUid(packageElement);
-            String packageStatus = packageLookup.extractStatus(packageElement.getQualifiedName().toString());
+            String packageStatus = packageLookup.extractStatus(packageElement);
             TocItem packageTocItem = new TocItem(packageUid, packageUid, packageStatus);
             //  build package summary
             packageMetadataFiles.add(packageBuilder.buildPackageMetadataFile(packageElement));

third_party/docfx-doclet-143274/src/main/java/com/microsoft/lookup/BaseLookup.java

@@ -1,21 +1,31 @@
 package com.microsoft.lookup;
 
 import com.microsoft.lookup.model.ExtendedMetadataFileItem;
-import com.microsoft.model.*;
+import com.microsoft.model.ExceptionItem;
+import com.microsoft.model.MetadataFileItem;
+import com.microsoft.model.MethodParameter;
+import com.microsoft.model.Return;
+import com.microsoft.model.TypeParameter;
 import com.microsoft.util.YamlUtil;
+import com.sun.source.doctree.DeprecatedTree;
 import com.sun.source.doctree.DocCommentTree;
 import com.sun.source.doctree.DocTree;
 import com.sun.source.doctree.LinkTree;
 import com.sun.source.doctree.LiteralTree;
+import com.sun.source.doctree.SeeTree;
 import jdk.javadoc.doclet.DocletEnvironment;
 import org.apache.commons.lang3.RegExUtils;
 import org.apache.commons.lang3.StringUtils;
 
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ElementKind;
-import javax.lang.model.element.Modifier;
-import javax.lang.model.element.TypeElement;
-import java.util.*;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
@@ -157,6 +167,20 @@ public String extractOverridden(T key) {
         return resolve(key).getOverridden();
     }
 
+    public String extractStatus(T element) {
+        Optional<DocCommentTree> docCommentTree = getDocCommentTree(element);
+        if (docCommentTree.isPresent()) {
+            boolean isDeprecated = docCommentTree.get().getBlockTags().stream()
+                    .filter(docTree -> docTree.getKind().equals(DocTree.Kind.DEPRECATED))
+                    .findFirst()
+                    .isPresent();
+            if (isDeprecated){
+                return DocTree.Kind.DEPRECATED.name().toLowerCase();
+            }
+        }
+        return null;
+    }
+
     protected String determineType(T element) {
         return elementKindLookup.get(element.getKind());
     }
@@ -166,10 +190,38 @@ protected String determinePackageName(T element) {
     }
 
     protected String determineComment(T element) {
-        return getDocCommentTree(element)
-                .map(DocCommentTree::getFullBody)
-                .map(this::replaceLinksAndCodes)
-                .orElse(null);
+        Optional<DocCommentTree> docCommentTree = getDocCommentTree(element);
+        if (docCommentTree.isPresent()) {
+            String comment = docCommentTree
+                    .map(DocCommentTree::getFullBody)
+                    .map(this::replaceLinksAndCodes)
+                    .orElse(null);
+            return replaceBlockTags(docCommentTree.get(), comment);
+        }
+        return null;
+    }
+
+    /**
+     * Provides support for deprecated and see tags
+     */
+    String replaceBlockTags(DocCommentTree docCommentTree, String comment) {
+        List<String> seeItems = new ArrayList<>();
+        String commentWithBlockTags = comment;
+        for (DocTree blockTag : docCommentTree.getBlockTags()) {
+            switch (blockTag.getKind()) {
+                case DEPRECATED:
+                    commentWithBlockTags = getDeprecatedSummary((DeprecatedTree) blockTag).concat(comment);
+                    break;
+                case SEE:
+                    seeItems.add(getSeeTagRef((SeeTree) blockTag));
+                    break;
+                default:
+            }
+        }
+        if (!seeItems.isEmpty()) {
+            commentWithBlockTags = commentWithBlockTags.concat(getSeeAlsoSummary(seeItems));
+        }
+        return commentWithBlockTags;
     }
 
     /**
@@ -231,4 +283,23 @@ public String makeTypeShort(String value) {
                 .map(s -> RegExUtils.removeAll(s, "\\b[a-z0-9_.]+\\."))
                 .collect(Collectors.joining("<"));
     }
+
+    private String getSeeAlsoSummary(List<String> seeItems) {
+        return String.format("\n<b>See Also:</b> %s\n", String.join(", ", seeItems));
+    }
+
+    private String getDeprecatedSummary(DeprecatedTree deprecatedTree) {
+        return String.format("\n<strong>Deprecated.</strong> <em>%s</em>\n\n",
+                replaceLinksAndCodes(deprecatedTree.getBody()));
+    }
+
+    private String getSeeTagRef(SeeTree seeTree) {
+        String ref = seeTree.getReference().stream()
+                .map(r -> String.valueOf(r)).collect(Collectors.joining(""));
+        // if it's already a tag, use that otherwise build xref tag
+        if (ref.matches("^<.+>.*")) {
+            return ref;
+        }
+        return String.format("<xref uid=\"%1$s\" data-throw-if-not-resolved=\"false\">%1$s</xref>", ref);
+    }
 }

third_party/docfx-doclet-143274/src/main/java/com/microsoft/lookup/ClassItemsLookup.java

@@ -14,6 +14,7 @@
 import javax.lang.model.type.TypeKind;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Optional;
 import java.util.stream.Collectors;
 
 public class ClassItemsLookup extends BaseLookup<Element> {
@@ -63,7 +64,7 @@ protected ExtendedMetadataFileItem buildMetadataFileItem(Element element) {
             result.setReturn(extractReturn(exeElement));
             if (exeElement.getKind() == ElementKind.METHOD) {
                 result.setOverridden(extractOverriddenUid(utils.overriddenMethod(exeElement)));
-                result.setSummary(getInheritedInlineCommentString(exeElement));
+                result.setSummary(determineComment(exeElement));
             }
         }
         result.setNameWithType(String.format("%s.%s", classSNameWithGenericsSupport, result.getName()));
@@ -79,15 +80,6 @@ protected ExtendedMetadataFileItem buildMetadataFileItem(Element element) {
         return result;
     }
 
-    public String extractDeprecatedDescription(Element element) {
-        return getDocCommentTree(element).map(docTree -> docTree.getBlockTags().stream()
-                .filter(o -> o.getKind() == DocTree.Kind.DEPRECATED)
-                .map(o -> (DeprecatedTree) o)
-                .map(o -> replaceLinksAndCodes(o.getBody()))
-                .findFirst().orElse(null)
-        ).orElse(null);
-    }
-
     List<MethodParameter> extractParameters(ExecutableElement element) {
         return element.getParameters().stream().map(o -> {
             String paramName = String.valueOf(o.getSimpleName());
@@ -156,19 +148,28 @@ String extractOverriddenUid(ExecutableElement ovr) {
         return "";
     }
 
+    private String determineComment(ExecutableElement methodElement) {
+        String inheritedInlineComment = getInheritedInlineCommentString(methodElement);
+        Optional<DocCommentTree> docCommentTree = getDocCommentTree(methodElement);
+        if (docCommentTree.isPresent()){
+            return replaceBlockTags(docCommentTree.get(), inheritedInlineComment);
+        }
+        return inheritedInlineComment;
+    }
+
     /**
      * If the item being inherited from is declared from external compiled package,
      * or is declared in the packages like java.lang.Object,
      * comments may be not available as doclet resolves from byte code.
      */
-    String getInheritedInlineCommentString(ExecutableElement exeElement) {
+    private String getInheritedInlineCommentString(ExecutableElement exeElement) {
         CommentHelper ch = getInheritedInlineTags(new CommentHelper(exeElement, utils));
         // Remove unresolved "@inheritDoc" tag.
         List<? extends DocTree> dctree = utils.removeBlockTag(ch.inlineTags, DocTree.Kind.INHERIT_DOC);
         return replaceLinksAndCodes(dctree);
     }
 
-    CommentHelper getInheritedInlineTags(CommentHelper input) {
+    private CommentHelper getInheritedInlineTags(CommentHelper input) {
         CommentHelper output = input.copy();
         if (!output.hasInheritDocTag() && !output.isSimpleOverride()) {
             return output;

third_party/docfx-doclet-143274/src/main/java/com/microsoft/lookup/ClassLookup.java

@@ -2,22 +2,23 @@
 
 import com.microsoft.lookup.model.ExtendedMetadataFileItem;
 import com.microsoft.model.MetadataFileItem;
-import com.microsoft.model.Status;
 import com.microsoft.model.TypeParameter;
 import com.microsoft.util.Utils;
-import com.sun.source.doctree.DeprecatedTree;
-import com.sun.source.doctree.DocTree;
 import jdk.javadoc.doclet.DocletEnvironment;
 import org.apache.commons.collections4.CollectionUtils;
 import org.apache.commons.lang3.StringUtils;
 
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ElementKind;
-import javax.lang.model.element.Modifier;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.type.TypeKind;
 import javax.lang.model.type.TypeMirror;
-import java.util.*;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.NoSuchElementException;
+import java.util.Optional;
+import java.util.Set;
 import java.util.stream.Collectors;
 
 public class ClassLookup extends BaseLookup<TypeElement> {
@@ -57,28 +58,6 @@ protected ExtendedMetadataFileItem buildMetadataFileItem(TypeElement classElemen
         return result;
     }
 
-    public String extractStatus(TypeElement classElement) {
-        DocTree deprecated = getDocCommentTree(classElement)
-                .map(docTree -> docTree.getBlockTags().stream()
-                        .filter(o -> o.getKind() == DocTree.Kind.DEPRECATED)
-                        .findFirst().orElse(null)
-                ).orElse(null);
-
-        if (deprecated != null) {
-            return Status.DEPRECATED.toString();
-        }
-        return null;
-    }
-
-    public String extractDeprecatedDescription(TypeElement classElement) {
-        return getDocCommentTree(classElement).map(docTree -> docTree.getBlockTags().stream()
-                .filter(o -> o.getKind() == DocTree.Kind.DEPRECATED)
-                .map(o -> (DeprecatedTree) o)
-                .map(o -> replaceLinksAndCodes(o.getBody()))
-                .findFirst().orElse(null)
-        ).orElse(null);
-    }
-
     void populateContent(TypeElement classElement, String shortNameWithGenericsSupport,
                          ExtendedMetadataFileItem container) {
         String type = elementKindLookup.get(classElement.getKind());

third_party/docfx-doclet-143274/src/main/java/com/microsoft/lookup/PackageLookup.java

@@ -5,7 +5,6 @@
 import jdk.javadoc.doclet.DocletEnvironment;
 
 import javax.lang.model.element.PackageElement;
-import javax.lang.model.element.TypeElement;
 
 public class PackageLookup extends BaseLookup<PackageElement> {
 
@@ -31,7 +30,8 @@ protected ExtendedMetadataFileItem buildMetadataFileItem(PackageElement packageE
         return result;
     }
 
-    public String extractStatus(String name) {
+    public String extractStatus(PackageElement packageElement) {
+        String name = String.valueOf(packageElement.getQualifiedName());
         if (name.contains(Status.ALPHA.toString())) {
             return Status.ALPHA.toString();
         }
@@ -46,9 +46,9 @@ String determinePackageContent(PackageElement packageElement) {
     }
 
     public String extractJavaType(PackageElement element) {
-        String javatype = element.getKind().name().toLowerCase().replaceAll("_","");
-        if (javatype.equals("package")){
-            return javatype;
+        String javaType = element.getKind().name().toLowerCase().replaceAll("_", "");
+        if (javaType.equals("package")) {
+            return javaType;
         }
         return null;
     }