Skip to content

Commit

Permalink
feat: include status field (#58)
Browse files Browse the repository at this point in the history 
* feat: include status field

includes 'deprecated' status + 'alpha'/'beta' package status

* chore: minor fixes

* chore: move deprecated message to summary + simplify
  • Loading branch information
@eaball35
eaball35 authored Sep 10, 2021
1 parent 5cd1c1a commit bcc064d
Show file tree
Hide file tree
Showing 26 changed files with 2,833 additions and 27 deletions.
42 changes: 36 additions & 6 deletions third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/YmlFilesBuilder.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,9 +68,9 @@ public boolean build() {
TocFile tocFile = new TocFile(outputPath, projectName);
for (PackageElement packageElement : elementUtil.extractPackageElements(environment.getIncludedElements())) {
String uid = packageLookup.extractUid(packageElement);
String status = packageLookup.extractStatus(packageElement.getQualifiedName().toString());
TocItem packageTocItem = new TocItem(uid, uid, status);
packageMetadataFiles.add(buildPackageMetadataFile(packageElement));

TocItem packageTocItem = new TocItem(uid, uid);
packageTocItem.getItems().add(new TocItem(uid, "Package summary"));
buildFilesForInnerClasses(packageElement, packageTocItem.getItems(), classMetadataFiles);
tocFile.addTocItem(packageTocItem);
Expand Down Expand Up @@ -102,8 +102,9 @@ void buildFilesForInnerClasses(Element element, List<TocItem> listToAddItems, Li
for (TypeElement classElement : elementUtil.extractSortedElements(element)) {
String uid = classLookup.extractUid(classElement);
String name = classLookup.extractTocName(classElement);
String status = classLookup.extractStatus(classElement);

listToAddItems.add(new TocItem(uid, name));
listToAddItems.add(new TocItem(uid, name, status));

container.add(buildClassYmlFile(classElement));
buildFilesForInnerClasses(classElement, listToAddItems, container);
Expand Down Expand Up @@ -171,9 +172,22 @@ void addClassInfo(TypeElement classElement, MetadataFile classMetadataFile) {
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());
}
classMetadataFile.getItems().add(classItem);
}

String getDeprecatedSummary(String depMsg, String summary){
String result = "(deprecated) " + depMsg;
if (summary != null && !summary.equals("")) {
result = result + " - " + summary;
}
return result;
}

void addChildren(TypeElement classElement, List<String> children) {
collect(classElement, children, ElementFilter::constructorsIn, classItemsLookup::extractUid);
collect(classElement, children, ElementFilter::methodsIn, classItemsLookup::extractUid);
Expand Down Expand Up @@ -201,6 +215,11 @@ 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);

addParameterReferences(constructorItem, classMetadataFile);
Expand All @@ -219,6 +238,11 @@ void addMethodsInfo(TypeElement classElement, MetadataFile classMetadataFile) {
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);
addExceptionReferences(methodItem, classMetadataFile);
Expand All @@ -235,6 +259,12 @@ void addFieldsInfo(TypeElement classElement, MetadataFile classMetadataFile) {
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);
addReturnReferences(fieldItem, classMetadataFile);
});
Expand Down Expand Up @@ -335,9 +365,9 @@ private void updateExternalReference(MetadataFileItem reference) {
}
}

private String updateReferenceUid(String uid){
private String updateReferenceUid(String uid) {
if (ENDING_PATTERN.matcher(uid).find()) {
uid = uid.replace("<?>","");
uid = uid.replace("<?>", "");
}
return uid;
}
Expand All @@ -346,7 +376,7 @@ private boolean isExternalReference(String uid) {
return (PROTOBUF_PATTERN.matcher(uid).find() || GAX_PATTERN.matcher(uid).find() || APICOMMON_PATTERN.matcher(uid).find() || GAX_PATTERN.matcher(uid).find() || LONGRUNNING_PATTERN.matcher(uid).find());
}

private boolean isJavaPrimitive(String uid) {
private boolean isJavaPrimitive(String uid) {
return (uid.equals("boolean") || uid.equals("int") || uid.equals("byte") || uid.equals("long") || uid.equals("float") || uid.equals("double") || uid.equals("char") || uid.equals("short"));
}

Expand Down
15 changes: 11 additions & 4 deletions third_party/docfx-doclet-143274/src/main/java/com/microsoft/lookup/ClassItemsLookup.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,8 @@
import com.microsoft.model.Return;
import com.microsoft.util.CommentHelper;
import com.microsoft.util.Utils;
import com.sun.source.doctree.DocTree;
import com.sun.source.doctree.*;
import com.sun.source.doctree.DocTree.Kind;
import com.sun.source.doctree.ParamTree;
import com.sun.source.doctree.ReturnTree;
import com.sun.source.doctree.ThrowsTree;
import jdk.javadoc.doclet.DocletEnvironment;

import javax.lang.model.element.*;
Expand Down Expand Up @@ -78,9 +75,19 @@ protected ExtendedMetadataFileItem buildMetadataFileItem(Element element) {
result.setFieldContent(String.format("%s %s %s", modifiers, type, elementQName));
result.setReturn(extractReturn((VariableElement) 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());
Expand Down
26 changes: 25 additions & 1 deletion third_party/docfx-doclet-143274/src/main/java/com/microsoft/lookup/ClassLookup.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,11 @@

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;
Expand Down Expand Up @@ -49,10 +52,31 @@ protected ExtendedMetadataFileItem buildMetadataFileItem(TypeElement classElemen
result.setInheritedMethods(determineInheritedMembers(inheritedMethods));
populateContent(classElement, classSNameWithGenericsSupport, result);
result.setTocName(classQName.replace(packageName.concat("."), ""));

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());
Expand Down
14 changes: 13 additions & 1 deletion third_party/docfx-doclet-143274/src/main/java/com/microsoft/lookup/PackageLookup.java
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
package com.microsoft.lookup;

import com.microsoft.lookup.model.ExtendedMetadataFileItem;
import com.microsoft.model.Status;
import com.sun.source.doctree.DeprecatedTree;
import com.sun.source.doctree.DocTree;
import jdk.javadoc.doclet.DocletEnvironment;

import javax.lang.model.element.PackageElement;
Expand All @@ -25,10 +28,19 @@ protected ExtendedMetadataFileItem buildMetadataFileItem(PackageElement packageE
result.setType(determineType(packageElement));
result.setSummary(determineComment(packageElement));
result.setContent(determinePackageContent(packageElement));

return result;
}

public String extractStatus(String name) {
if (name.contains(Status.ALPHA.toString())) {
return Status.ALPHA.toString();
}
if (name.contains(Status.BETA.toString())) {
return Status.BETA.toString();
}
return null;
}

String determinePackageContent(PackageElement packageElement) {
return "package " + packageElement.getQualifiedName();
}
Expand Down
22 changes: 12 additions & 10 deletions third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/MetadataFileItem.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

@JsonPropertyOrder({"uid", "id", "parent", "children", "href", "langs", "isExternal", "name", "nameWithType",
"fullName", "overload", "overridden", "type", "package", "summary", "syntax", "inheritance", "implements", "exceptions",
"spec.java", "inheritedMembers"})
"spec.java", "inheritedMembers", "status"})
public class MetadataFileItem implements Comparable<MetadataFileItem> {

private final String uid;
Expand Down Expand Up @@ -38,6 +38,7 @@ public class MetadataFileItem implements Comparable<MetadataFileItem> {
private List<SpecViewModel> specForJava = new ArrayList<>();
@JsonProperty("inheritedMembers")
private List<String> inheritedMethods = new ArrayList<>();
private String status;

@Override
public int compareTo(MetadataFileItem item) {
Expand Down Expand Up @@ -241,12 +242,9 @@ public String getOverridden() {

@Override
public boolean equals(Object o) {
if (this == o) {
return true;
}
if (o == null || getClass() != o.getClass()) {
return false;
}
if (this == o) { return true; }

if (o == null || getClass() != o.getClass()) { return false; }

MetadataFileItem that = (MetadataFileItem) o;

Expand All @@ -262,11 +260,15 @@ public Boolean getIsExternal() {
return isExternal ? true : null;
}

public void setIsExternal(boolean external) {
isExternal = external;
}

public String handleGenericForOverLoad(String value) {
return RegExUtils.removeAll(value, "<\\w+(,\\s*\\w+)*>");
}

public void setIsExternal(boolean external) {
isExternal = external;
}
public String getStatus() { return status; }

public void setStatus(String status) { this.status = status; }
}
26 changes: 26 additions & 0 deletions third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/Status.java
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
/*
* Copyright 2021 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

package com.microsoft.model;

public enum Status {
DEPRECATED, ALPHA, BETA;

@Override
public String toString() {
return name().toLowerCase();
}
}
9 changes: 9 additions & 0 deletions third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/TocItem.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,20 @@ public class TocItem {

private final String uid;
private final String name;
private String status;
private List<TocItem> items = new ArrayList<>();

public TocItem(String uid, String name) {
this.uid = uid;
this.name = name;
}

public TocItem(String uid, String name, String status) {
this.uid = uid;
this.name = name;
this.status = status;
}

public String getUid() {
return uid;
}
Expand All @@ -25,4 +32,6 @@ public String getName() {
public List<TocItem> getItems() {
return items;
}

public String getStatus() { return status; }
}
27 changes: 27 additions & 0 deletions third_party/docfx-doclet-143274/src/test/java/com/microsoft/lookup/ClassItemsLookupTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ public class ClassItemsLookupTest {
private ParamTree paramTree;
private ThrowsTree throwsTree;
private ReturnTree returnTree;
private DeprecatedTree deprecatedTree;
private TextTree textTree;
private IdentifierTree identifierTree;
private ClassItemsLookup classItemsLookup;
Expand All @@ -52,9 +53,11 @@ public void setup() {
paramTree = Mockito.mock(ParamTree.class);
throwsTree = Mockito.mock(ThrowsTree.class);
returnTree = Mockito.mock(ReturnTree.class);
deprecatedTree = Mockito.mock(DeprecatedTree.class);
textTree = Mockito.mock(TextTree.class);
identifierTree = Mockito.mock(IdentifierTree.class);
classItemsLookup = new ClassItemsLookup(environment);

}

@Test
Expand Down Expand Up @@ -262,4 +265,28 @@ public void determineTypeForEnumConstant() {
assertEquals(classItemsLookup.determineType(element.getEnclosedElements().get(0)), "Field");
assertEquals(classItemsLookup.determineType(element.getEnclosedElements().get(1)), "Field");
}

@Test
public void extractDeprecatedDescription() {
TypeElement element = elements.getTypeElement("com.microsoft.samples.agreements.AgreementDetailsCollectionOperations");
ExecutableElement method = ElementFilter.methodsIn(element.getEnclosedElements()).get(0);
String depMsg = "Deprecated Message :(";

when(environment.getDocTrees()).thenReturn(docTrees);
when(docTrees.getDocCommentTree(method)).thenReturn(docCommentTree);
doReturn(Arrays.asList(deprecatedTree)).when(docCommentTree).getBlockTags();
when(deprecatedTree.getKind()).thenReturn(Kind.DEPRECATED);

doReturn(Arrays.asList(textTree)).when(deprecatedTree).getBody();
when(textTree.getKind()).thenReturn(Kind.TEXT);
when(textTree.toString()).thenReturn(depMsg);

String result = classItemsLookup.extractDeprecatedDescription(method);

verify(environment).getDocTrees();
verify(docTrees).getDocCommentTree(method);
verify(docCommentTree).getBlockTags();
verify(deprecatedTree).getKind();
assertEquals("Wrong description", result, depMsg);
}
}
Loading

0 comments on commit bcc064d

Please sign in to comment.