Skip to content

Commit bcc064d

Browse files
eaball35eaball35
authored
feat: include status field (#58)
* feat: include status field includes 'deprecated' status + 'alpha'/'beta' package status * chore: minor fixes * chore: move deprecated message to summary + simplify
1 parent 5cd1c1a commit bcc064d

26 files changed

Lines changed: 2833 additions & 27 deletions

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

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -68,9 +68,9 @@ public boolean build() {
6868
TocFile tocFile = new TocFile(outputPath, projectName);
6969
for (PackageElement packageElement : elementUtil.extractPackageElements(environment.getIncludedElements())) {
7070
String uid = packageLookup.extractUid(packageElement);
71+
String status = packageLookup.extractStatus(packageElement.getQualifiedName().toString());
72+
TocItem packageTocItem = new TocItem(uid, uid, status);
7173
packageMetadataFiles.add(buildPackageMetadataFile(packageElement));
72-
73-
TocItem packageTocItem = new TocItem(uid, uid);
7474
packageTocItem.getItems().add(new TocItem(uid, "Package summary"));
7575
buildFilesForInnerClasses(packageElement, packageTocItem.getItems(), classMetadataFiles);
7676
tocFile.addTocItem(packageTocItem);
@@ -102,8 +102,9 @@ void buildFilesForInnerClasses(Element element, List<TocItem> listToAddItems, Li
102102
for (TypeElement classElement : elementUtil.extractSortedElements(element)) {
103103
String uid = classLookup.extractUid(classElement);
104104
String name = classLookup.extractTocName(classElement);
105+
String status = classLookup.extractStatus(classElement);
105106

106-
listToAddItems.add(new TocItem(uid, name));
107+
listToAddItems.add(new TocItem(uid, name, status));
107108

108109
container.add(buildClassYmlFile(classElement));
109110
buildFilesForInnerClasses(classElement, listToAddItems, container);
@@ -171,9 +172,22 @@ void addClassInfo(TypeElement classElement, MetadataFile classMetadataFile) {
171172
classItem.setInheritance(classLookup.extractSuperclass(classElement));
172173
classItem.setInterfaces(classLookup.extractInterfaces(classElement));
173174
classItem.setInheritedMethods(classLookup.extractInheritedMethods(classElement));
175+
String depMsg = classLookup.extractDeprecatedDescription(classElement);
176+
if (depMsg != null) {
177+
classItem.setSummary(getDeprecatedSummary(depMsg, classItem.getSummary()));
178+
classItem.setStatus(Status.DEPRECATED.toString());
179+
}
174180
classMetadataFile.getItems().add(classItem);
175181
}
176182

183+
String getDeprecatedSummary(String depMsg, String summary){
184+
String result = "(deprecated) " + depMsg;
185+
if (summary != null && !summary.equals("")) {
186+
result = result + " - " + summary;
187+
}
188+
return result;
189+
}
190+
177191
void addChildren(TypeElement classElement, List<String> children) {
178192
collect(classElement, children, ElementFilter::constructorsIn, classItemsLookup::extractUid);
179193
collect(classElement, children, ElementFilter::methodsIn, classItemsLookup::extractUid);
@@ -201,6 +215,11 @@ void addConstructorsInfo(TypeElement classElement, MetadataFile classMetadataFil
201215
constructorItem.setOverload(classItemsLookup.extractOverload(constructorElement));
202216
constructorItem.setContent(classItemsLookup.extractConstructorContent(constructorElement));
203217
constructorItem.setParameters(classItemsLookup.extractParameters(constructorElement));
218+
String depMsg = classItemsLookup.extractDeprecatedDescription(constructorElement);
219+
if (depMsg != null) {
220+
constructorItem.setSummary(getDeprecatedSummary(depMsg, constructorItem.getSummary()));
221+
constructorItem.setStatus(Status.DEPRECATED.toString());
222+
}
204223
classMetadataFile.getItems().add(constructorItem);
205224

206225
addParameterReferences(constructorItem, classMetadataFile);
@@ -219,6 +238,11 @@ void addMethodsInfo(TypeElement classElement, MetadataFile classMetadataFile) {
219238
methodItem.setParameters(classItemsLookup.extractParameters(methodElement));
220239
methodItem.setReturn(classItemsLookup.extractReturn(methodElement));
221240
methodItem.setOverridden(classItemsLookup.extractOverridden(methodElement));
241+
String depMsg = classItemsLookup.extractDeprecatedDescription(methodElement);
242+
if (depMsg != null) {
243+
methodItem.setSummary(getDeprecatedSummary(depMsg, methodItem.getSummary()));
244+
methodItem.setStatus(Status.DEPRECATED.toString());
245+
}
222246

223247
classMetadataFile.getItems().add(methodItem);
224248
addExceptionReferences(methodItem, classMetadataFile);
@@ -235,6 +259,12 @@ void addFieldsInfo(TypeElement classElement, MetadataFile classMetadataFile) {
235259
MetadataFileItem fieldItem = buildMetadataFileItem(fieldElement);
236260
fieldItem.setContent(classItemsLookup.extractFieldContent(fieldElement));
237261
fieldItem.setReturn(classItemsLookup.extractReturn(fieldElement));
262+
String depMsg = classItemsLookup.extractDeprecatedDescription(fieldElement);
263+
if (depMsg != null) {
264+
fieldItem.setSummary(getDeprecatedSummary(depMsg, fieldItem.getSummary()));
265+
fieldItem.setStatus(Status.DEPRECATED.toString());
266+
}
267+
238268
classMetadataFile.getItems().add(fieldItem);
239269
addReturnReferences(fieldItem, classMetadataFile);
240270
});
@@ -335,9 +365,9 @@ private void updateExternalReference(MetadataFileItem reference) {
335365
}
336366
}
337367

338-
private String updateReferenceUid(String uid){
368+
private String updateReferenceUid(String uid) {
339369
if (ENDING_PATTERN.matcher(uid).find()) {
340-
uid = uid.replace("<?>","");
370+
uid = uid.replace("<?>", "");
341371
}
342372
return uid;
343373
}
@@ -346,7 +376,7 @@ private boolean isExternalReference(String uid) {
346376
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());
347377
}
348378

349-
private boolean isJavaPrimitive(String uid) {
379+
private boolean isJavaPrimitive(String uid) {
350380
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"));
351381
}
352382

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

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,8 @@
66
import com.microsoft.model.Return;
77
import com.microsoft.util.CommentHelper;
88
import com.microsoft.util.Utils;
9-
import com.sun.source.doctree.DocTree;
9+
import com.sun.source.doctree.*;
1010
import com.sun.source.doctree.DocTree.Kind;
11-
import com.sun.source.doctree.ParamTree;
12-
import com.sun.source.doctree.ReturnTree;
13-
import com.sun.source.doctree.ThrowsTree;
1411
import jdk.javadoc.doclet.DocletEnvironment;
1512

1613
import javax.lang.model.element.*;
@@ -78,9 +75,19 @@ protected ExtendedMetadataFileItem buildMetadataFileItem(Element element) {
7875
result.setFieldContent(String.format("%s %s %s", modifiers, type, elementQName));
7976
result.setReturn(extractReturn((VariableElement) element));
8077
}
78+
8179
return result;
8280
}
8381

82+
public String extractDeprecatedDescription(Element element) {
83+
return getDocCommentTree(element).map(docTree -> docTree.getBlockTags().stream()
84+
.filter(o -> o.getKind() == DocTree.Kind.DEPRECATED)
85+
.map(o -> (DeprecatedTree) o)
86+
.map(o -> replaceLinksAndCodes(o.getBody()))
87+
.findFirst().orElse(null)
88+
).orElse(null);
89+
}
90+
8491
List<MethodParameter> extractParameters(ExecutableElement element) {
8592
return element.getParameters().stream().map(o -> {
8693
String paramName = String.valueOf(o.getSimpleName());

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

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,11 @@
22

33
import com.microsoft.lookup.model.ExtendedMetadataFileItem;
44
import com.microsoft.model.MetadataFileItem;
5+
import com.microsoft.model.Status;
56
import com.microsoft.model.TypeParameter;
67
import com.microsoft.util.Utils;
8+
import com.sun.source.doctree.DeprecatedTree;
9+
import com.sun.source.doctree.DocTree;
710
import jdk.javadoc.doclet.DocletEnvironment;
811
import org.apache.commons.collections4.CollectionUtils;
912
import org.apache.commons.lang3.StringUtils;
@@ -49,10 +52,31 @@ protected ExtendedMetadataFileItem buildMetadataFileItem(TypeElement classElemen
4952
result.setInheritedMethods(determineInheritedMembers(inheritedMethods));
5053
populateContent(classElement, classSNameWithGenericsSupport, result);
5154
result.setTocName(classQName.replace(packageName.concat("."), ""));
52-
5355
return result;
5456
}
5557

58+
public String extractStatus(TypeElement classElement) {
59+
DocTree deprecated = getDocCommentTree(classElement)
60+
.map(docTree -> docTree.getBlockTags().stream()
61+
.filter(o -> o.getKind() == DocTree.Kind.DEPRECATED)
62+
.findFirst().orElse(null)
63+
).orElse(null);
64+
65+
if (deprecated != null) {
66+
return Status.DEPRECATED.toString();
67+
}
68+
return null;
69+
}
70+
71+
public String extractDeprecatedDescription(TypeElement classElement) {
72+
return getDocCommentTree(classElement).map(docTree -> docTree.getBlockTags().stream()
73+
.filter(o -> o.getKind() == DocTree.Kind.DEPRECATED)
74+
.map(o -> (DeprecatedTree) o)
75+
.map(o -> replaceLinksAndCodes(o.getBody()))
76+
.findFirst().orElse(null)
77+
).orElse(null);
78+
}
79+
5680
void populateContent(TypeElement classElement, String shortNameWithGenericsSupport,
5781
ExtendedMetadataFileItem container) {
5882
String type = elementKindLookup.get(classElement.getKind());

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

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
package com.microsoft.lookup;
22

33
import com.microsoft.lookup.model.ExtendedMetadataFileItem;
4+
import com.microsoft.model.Status;
5+
import com.sun.source.doctree.DeprecatedTree;
6+
import com.sun.source.doctree.DocTree;
47
import jdk.javadoc.doclet.DocletEnvironment;
58

69
import javax.lang.model.element.PackageElement;
@@ -25,10 +28,19 @@ protected ExtendedMetadataFileItem buildMetadataFileItem(PackageElement packageE
2528
result.setType(determineType(packageElement));
2629
result.setSummary(determineComment(packageElement));
2730
result.setContent(determinePackageContent(packageElement));
28-
2931
return result;
3032
}
3133

34+
public String extractStatus(String name) {
35+
if (name.contains(Status.ALPHA.toString())) {
36+
return Status.ALPHA.toString();
37+
}
38+
if (name.contains(Status.BETA.toString())) {
39+
return Status.BETA.toString();
40+
}
41+
return null;
42+
}
43+
3244
String determinePackageContent(PackageElement packageElement) {
3345
return "package " + packageElement.getQualifiedName();
3446
}

‎third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/MetadataFileItem.java‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010

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

1616
private final String uid;
@@ -38,6 +38,7 @@ public class MetadataFileItem implements Comparable<MetadataFileItem> {
3838
private List<SpecViewModel> specForJava = new ArrayList<>();
3939
@JsonProperty("inheritedMembers")
4040
private List<String> inheritedMethods = new ArrayList<>();
41+
private String status;
4142

4243
@Override
4344
public int compareTo(MetadataFileItem item) {
@@ -241,12 +242,9 @@ public String getOverridden() {
241242

242243
@Override
243244
public boolean equals(Object o) {
244-
if (this == o) {
245-
return true;
246-
}
247-
if (o == null || getClass() != o.getClass()) {
248-
return false;
249-
}
245+
if (this == o) { return true; }
246+
247+
if (o == null || getClass() != o.getClass()) { return false; }
250248

251249
MetadataFileItem that = (MetadataFileItem) o;
252250

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

263+
public void setIsExternal(boolean external) {
264+
isExternal = external;
265+
}
266+
265267
public String handleGenericForOverLoad(String value) {
266268
return RegExUtils.removeAll(value, "<\\w+(,\\s*\\w+)*>");
267269
}
268270

269-
public void setIsExternal(boolean external) {
270-
isExternal = external;
271-
}
271+
public String getStatus() { return status; }
272+
273+
public void setStatus(String status) { this.status = status; }
272274
}

‎third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/Status.java‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
/*
2+
* Copyright 2021 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.microsoft.model;
18+
19+
public enum Status {
20+
DEPRECATED, ALPHA, BETA;
21+
22+
@Override
23+
public String toString() {
24+
return name().toLowerCase();
25+
}
26+
}

‎third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/TocItem.java‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,20 @@ public class TocItem {
77

88
private final String uid;
99
private final String name;
10+
private String status;
1011
private List<TocItem> items = new ArrayList<>();
1112

1213
public TocItem(String uid, String name) {
1314
this.uid = uid;
1415
this.name = name;
1516
}
1617

18+
public TocItem(String uid, String name, String status) {
19+
this.uid = uid;
20+
this.name = name;
21+
this.status = status;
22+
}
23+
1724
public String getUid() {
1825
return uid;
1926
}
@@ -25,4 +32,6 @@ public String getName() {
2532
public List<TocItem> getItems() {
2633
return items;
2734
}
35+
36+
public String getStatus() { return status; }
2837
}

‎third_party/docfx-doclet-143274/src/test/java/com/microsoft/lookup/ClassItemsLookupTest.java‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ public class ClassItemsLookupTest {
3939
private ParamTree paramTree;
4040
private ThrowsTree throwsTree;
4141
private ReturnTree returnTree;
42+
private DeprecatedTree deprecatedTree;
4243
private TextTree textTree;
4344
private IdentifierTree identifierTree;
4445
private ClassItemsLookup classItemsLookup;
@@ -52,9 +53,11 @@ public void setup() {
5253
paramTree = Mockito.mock(ParamTree.class);
5354
throwsTree = Mockito.mock(ThrowsTree.class);
5455
returnTree = Mockito.mock(ReturnTree.class);
56+
deprecatedTree = Mockito.mock(DeprecatedTree.class);
5557
textTree = Mockito.mock(TextTree.class);
5658
identifierTree = Mockito.mock(IdentifierTree.class);
5759
classItemsLookup = new ClassItemsLookup(environment);
60+
5861
}
5962

6063
@Test
@@ -262,4 +265,28 @@ public void determineTypeForEnumConstant() {
262265
assertEquals(classItemsLookup.determineType(element.getEnclosedElements().get(0)), "Field");
263266
assertEquals(classItemsLookup.determineType(element.getEnclosedElements().get(1)), "Field");
264267
}
268+
269+
@Test
270+
public void extractDeprecatedDescription() {
271+
TypeElement element = elements.getTypeElement("com.microsoft.samples.agreements.AgreementDetailsCollectionOperations");
272+
ExecutableElement method = ElementFilter.methodsIn(element.getEnclosedElements()).get(0);
273+
String depMsg = "Deprecated Message :(";
274+
275+
when(environment.getDocTrees()).thenReturn(docTrees);
276+
when(docTrees.getDocCommentTree(method)).thenReturn(docCommentTree);
277+
doReturn(Arrays.asList(deprecatedTree)).when(docCommentTree).getBlockTags();
278+
when(deprecatedTree.getKind()).thenReturn(Kind.DEPRECATED);
279+
280+
doReturn(Arrays.asList(textTree)).when(deprecatedTree).getBody();
281+
when(textTree.getKind()).thenReturn(Kind.TEXT);
282+
when(textTree.toString()).thenReturn(depMsg);
283+
284+
String result = classItemsLookup.extractDeprecatedDescription(method);
285+
286+
verify(environment).getDocTrees();
287+
verify(docTrees).getDocCommentTree(method);
288+
verify(docCommentTree).getBlockTags();
289+
verify(deprecatedTree).getKind();
290+
assertEquals("Wrong description", result, depMsg);
291+
}
265292
}

0 commit comments

Comments
 (0)