Skip to content
This repository was archived by the owner on Aug 9, 2022. It is now read-only.

Commit f1575f7

Browse files
anmeng10101anmeng10101
authored
May Release For 2020 (#34)
* not document package private (default modifier) elements (#32) * resolve the uid for context in @link (#33) * add items in specForJava to localLookup context * add fuzzy resolve for @link content
1 parent de69fe1 commit f1575f7

7 files changed

Lines changed: 169 additions & 74 deletions

File tree

‎src/main/java/com/microsoft/build/Lookup.java‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
import static org.apache.commons.lang3.RegExUtils.replaceAll;
55

66
import com.microsoft.model.MetadataFile;
7+
78
import java.util.HashMap;
89
import java.util.LinkedHashMap;
910
import java.util.List;
@@ -54,6 +55,8 @@ private void consume(List<MetadataFile> metadataFiles) {
5455
* Logic of {@link YmlFilesBuilder#resolveUidByLookup} based on this for case when @link starts from '#'
5556
*/
5657
Map<String, String> map = new LinkedHashMap<>();
58+
Map<String, String> specForJavaMap = new LinkedHashMap<>();
59+
5760
file.getItems().forEach(item -> {
5861
String uid = item.getUid();
5962
String nameWithType = item.getNameWithType();
@@ -71,13 +74,26 @@ private void consume(List<MetadataFile> metadataFiles) {
7174
map.put(replaceAll(removeAll(uid, UID_PACKAGE_NAME_REGEXP), ",", ", "), uid);
7275
map.put(replaceAll(removeAll(nameWithTypeWithoutGenerics, METHOD_PARAMS_REGEXP), ", ", ","), uid);
7376
});
77+
7478
file.getReferences().forEach(item -> {
75-
map.put(item.getNameWithType(), item.getUid());
7679
map.put(item.getUid(), item.getUid());
80+
81+
// complex types are recorded in "specForJava" as arrayList of items, thus it has no "NameWithType"
82+
// thus we need to get every reference item from specForJava, and add to localLookup
83+
if (item.getNameWithType() == null || item.getNameWithType().isEmpty()) {
84+
item.getSpecForJava().forEach(spec -> {
85+
specForJavaMap.put(spec.getName(), spec.getUid());
86+
specForJavaMap.put(spec.getFullName(), spec.getUid());
87+
});
88+
} else {
89+
map.put(item.getNameWithType(), item.getUid());
90+
}
7791
});
7892

79-
localLookupByFileName.put(file.getFileNameWithPath(), map);
93+
// to avoid conflict, the items from specForJava should only add to localLookup
8094
globalLookup.putAll(map);
95+
map.putAll(specForJavaMap);
96+
localLookupByFileName.put(file.getFileNameWithPath(), map);
8197
});
8298
}
8399
}

‎src/main/java/com/microsoft/build/YmlFilesBuilder.java‎

Lines changed: 60 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -4,46 +4,30 @@
44
import com.microsoft.lookup.ClassItemsLookup;
55
import com.microsoft.lookup.ClassLookup;
66
import com.microsoft.lookup.PackageLookup;
7-
import com.microsoft.model.MetadataFile;
8-
import com.microsoft.model.MetadataFileItem;
9-
import com.microsoft.model.SpecViewModel;
10-
import com.microsoft.model.TocFile;
11-
import com.microsoft.model.TocItem;
7+
import com.microsoft.model.*;
128
import com.microsoft.util.ElementUtil;
139
import com.microsoft.util.FileUtil;
1410
import com.microsoft.util.YamlUtil;
11+
import jdk.javadoc.doclet.DocletEnvironment;
12+
import org.apache.commons.lang3.RegExUtils;
13+
import org.apache.commons.lang3.StringUtils;
1514

16-
import java.util.ArrayList;
17-
import java.util.Arrays;
18-
import java.util.Iterator;
19-
import java.util.LinkedHashSet;
20-
import java.util.List;
21-
import java.util.Objects;
22-
import java.util.Optional;
23-
import java.util.Set;
15+
import javax.lang.model.element.*;
16+
import javax.lang.model.util.ElementFilter;
17+
import java.util.*;
2418
import java.util.function.Function;
2519
import java.util.regex.Matcher;
2620
import java.util.regex.Pattern;
2721
import java.util.stream.Collectors;
2822
import java.util.stream.Stream;
29-
import javax.lang.model.element.Element;
30-
import javax.lang.model.element.ExecutableElement;
31-
import javax.lang.model.element.Modifier;
32-
import javax.lang.model.element.PackageElement;
33-
import javax.lang.model.element.TypeElement;
34-
import javax.lang.model.util.ElementFilter;
35-
36-
import jdk.javadoc.doclet.DocletEnvironment;
37-
38-
import org.apache.commons.lang3.RegExUtils;
39-
import org.apache.commons.lang3.StringUtils;
4023

4124

4225
public class YmlFilesBuilder {
4326

4427
private final static String[] LANGS = {"java"};
4528
private final Pattern XREF_LINK_PATTERN = Pattern.compile("<xref uid=\".*?\" .*?>.*?</xref>");
4629
private final Pattern XREF_LINK_CONTENT_PATTERN = Pattern.compile("(?<=<xref uid=\").*?(?=\" .*?>.*?</xref>)");
30+
private final Pattern XREF_LINK_RESOLVE_PATTERN = Pattern.compile("(?<class>\\w+)\\#(?<member>\\w+)(\\((?<param>.*)\\))?");
4731

4832
private DocletEnvironment environment;
4933
private String outputPath;
@@ -182,7 +166,7 @@ void addChildren(TypeElement classElement, List<String> children) {
182166

183167
List<? extends Element> filterPrivateElements(List<? extends Element> elements) {
184168
return elements.stream()
185-
.filter(element -> !element.getModifiers().contains(Modifier.PRIVATE)).collect(Collectors.toList());
169+
.filter(element -> !ElementUtil.isPrivateOrPackagePrivate(element)).collect(Collectors.toList());
186170
}
187171

188172
void collect(TypeElement classElement, List<String> children,
@@ -209,7 +193,7 @@ void addConstructorsInfo(TypeElement classElement, MetadataFile classMetadataFil
209193

210194
void addMethodsInfo(TypeElement classElement, MetadataFile classMetadataFile) {
211195
ElementFilter.methodsIn(classElement.getEnclosedElements()).stream()
212-
.filter(methodElement -> !methodElement.getModifiers().contains(Modifier.PRIVATE))
196+
.filter(methodElement -> !ElementUtil.isPrivateOrPackagePrivate(methodElement))
213197
.forEach(methodElement -> {
214198
MetadataFileItem methodItem = buildMetadataFileItem(methodElement);
215199
methodItem.setOverload(classItemsLookup.extractOverload(methodElement));
@@ -228,7 +212,7 @@ void addMethodsInfo(TypeElement classElement, MetadataFile classMetadataFile) {
228212

229213
void addFieldsInfo(TypeElement classElement, MetadataFile classMetadataFile) {
230214
ElementFilter.fieldsIn(classElement.getEnclosedElements()).stream()
231-
.filter(fieldElement -> !fieldElement.getModifiers().contains(Modifier.PRIVATE))
215+
.filter(fieldElement -> !ElementUtil.isPrivateOrPackagePrivate(fieldElement))
232216
.forEach(fieldElement -> {
233217
MetadataFileItem fieldItem = buildMetadataFileItem(fieldElement);
234218
fieldItem.setContent(classItemsLookup.extractFieldContent(fieldElement));
@@ -392,25 +376,40 @@ String populateUidValues(String text, LookupContext lookupContext) {
392376
}
393377

394378
String linkContent = linkContentMatcher.group();
395-
String uid = resolveUidByLookup(linkContent, lookupContext);
379+
String uid = resolveUidFromLinkContent(linkContent, lookupContext);
396380
String updatedLink = linkContentMatcher.replaceAll(uid);
397381
text = StringUtils.replace(text, link, updatedLink);
398382
}
399383
return text;
400384
}
401385

402-
String resolveUidByLookup(String linkContent, LookupContext lookupContext) {
386+
/**
387+
* The linkContent could be in following format
388+
* #memeber
389+
* Class#member
390+
* Class#method()
391+
* Class#method(params)
392+
*/
393+
String resolveUidFromLinkContent(String linkContent, LookupContext lookupContext) {
403394
if (StringUtils.isBlank(linkContent)) {
404395
return "";
405396
}
406397

407398
linkContent = linkContent.trim();
399+
400+
// complete class name for class internal link
408401
if (linkContent.startsWith("#")) {
409402
String firstKey = lookupContext.getOwnerUid();
410403
linkContent = firstKey + linkContent;
411404
}
405+
406+
// fuzzy resolve, target for items from project external references
407+
String fuzzyResolvedUid = resolveUidFromReference(linkContent, lookupContext);
408+
409+
// exact resolve in lookupContext
412410
linkContent = linkContent.replace("#", ".");
413-
return lookupContext.containsKey(linkContent) ? lookupContext.resolve(linkContent) : "";
411+
String exactResolveUid = resolveUidByLookup(linkContent, lookupContext);
412+
return exactResolveUid.isEmpty() ? fuzzyResolvedUid : exactResolveUid;
414413
}
415414

416415
List<String> splitUidWithGenericsIntoClassNames(String uid) {
@@ -464,4 +463,35 @@ else if (uid != "")
464463

465464
return specList;
466465
}
466+
467+
/**
468+
* this method is used to do fuzzy resolve
469+
* "*" will be added at the end of uid for method for xerf service resolve purpose
470+
*/
471+
String resolveUidFromReference(String linkContent, LookupContext lookupContext) {
472+
String uid = "";
473+
Matcher matcher = XREF_LINK_RESOLVE_PATTERN.matcher(linkContent);
474+
475+
if (matcher.find()) {
476+
String className = matcher.group("class");
477+
String memberName = matcher.group("member");
478+
uid = resolveUidByLookup(className, lookupContext);
479+
if (!uid.isEmpty()) {
480+
uid = uid.concat(".").concat(memberName);
481+
482+
// linkContent targets a method
483+
if (!StringUtils.isBlank(matcher.group(3))) {
484+
uid = uid.concat("*");
485+
}
486+
}
487+
}
488+
return uid;
489+
}
490+
491+
String resolveUidByLookup(String signature, LookupContext lookupContext){
492+
if (StringUtils.isBlank(signature) || lookupContext == null) {
493+
return "";
494+
}
495+
return lookupContext.containsKey(signature) ? lookupContext.resolve(signature) : "";
496+
}
467497
}

‎src/main/java/com/microsoft/lookup/ClassLookup.java‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,18 @@
33
import com.microsoft.lookup.model.ExtendedMetadataFileItem;
44
import com.microsoft.model.MetadataFileItem;
55
import com.microsoft.model.TypeParameter;
6+
import com.microsoft.util.ElementUtil;
7+
import jdk.javadoc.doclet.DocletEnvironment;
8+
import org.apache.commons.collections4.CollectionUtils;
9+
import org.apache.commons.lang3.StringUtils;
610

7-
import java.util.*;
8-
import java.util.stream.Collectors;
911
import javax.lang.model.element.Element;
1012
import javax.lang.model.element.ElementKind;
11-
import javax.lang.model.element.Modifier;
1213
import javax.lang.model.element.TypeElement;
1314
import javax.lang.model.type.TypeKind;
1415
import javax.lang.model.type.TypeMirror;
15-
16-
import jdk.javadoc.doclet.DocletEnvironment;
17-
import org.apache.commons.collections4.CollectionUtils;
18-
import org.apache.commons.lang3.StringUtils;
16+
import java.util.*;
17+
import java.util.stream.Collectors;
1918

2019
public class ClassLookup extends BaseLookup<TypeElement> {
2120

@@ -147,7 +146,7 @@ void appendInheritedMethods(TypeElement element, List<ExtendedMetadataFileItem>
147146
.orElse(0);
148147

149148
for (Element m : members) {
150-
if (m.getKind() == ElementKind.METHOD && !m.getModifiers().contains(Modifier.PRIVATE)) {
149+
if (m.getKind() == ElementKind.METHOD && !ElementUtil.isPrivateOrPackagePrivate(m)) {
151150
String uid = element.getQualifiedName().toString().concat(".") + String.valueOf(m);
152151

153152
ExtendedMetadataFileItem item = new ExtendedMetadataFileItem(uid);

‎src/main/java/com/microsoft/util/ElementUtil.java‎

Lines changed: 27 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
11
package com.microsoft.util;
22

3+
import org.apache.commons.lang3.StringUtils;
4+
5+
import javax.lang.model.element.Element;
6+
import javax.lang.model.element.Modifier;
7+
import javax.lang.model.element.PackageElement;
8+
import javax.lang.model.element.TypeElement;
9+
import javax.lang.model.util.ElementFilter;
310
import java.util.HashSet;
411
import java.util.List;
512
import java.util.Set;
613
import java.util.regex.Pattern;
714
import java.util.stream.Collectors;
815
import java.util.stream.Stream;
9-
import javax.lang.model.element.Element;
10-
import javax.lang.model.element.PackageElement;
11-
import javax.lang.model.element.TypeElement;
12-
import javax.lang.model.util.ElementFilter;
13-
import org.apache.commons.lang3.StringUtils;
1416

1517
public class ElementUtil {
1618

@@ -49,4 +51,24 @@ boolean matchAnyPattern(Set<Pattern> patterns, String stringToCheck) {
4951
}
5052
return false;
5153
}
54+
55+
public static boolean isPackagePrivate(Element e) {
56+
return !(isPublic(e) || isPrivate(e) || isProtected(e));
57+
}
58+
59+
public static boolean isPrivate(Element e) {
60+
return e.getModifiers().contains(Modifier.PRIVATE);
61+
}
62+
63+
public static boolean isProtected(Element e) {
64+
return e.getModifiers().contains(Modifier.PROTECTED);
65+
}
66+
67+
public static boolean isPublic(Element e) {
68+
return e.getModifiers().contains(Modifier.PUBLIC);
69+
}
70+
71+
public static boolean isPrivateOrPackagePrivate(Element e) {
72+
return isPrivate(e) || isPackagePrivate(e);
73+
}
5274
}

‎src/test/java/com/microsoft/build/YmlFilesBuilderTest.java‎

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
import com.microsoft.model.MethodParameter;
1212
import com.microsoft.model.Syntax;
1313
import com.sun.source.util.DocTrees;
14+
1415
import java.io.File;
1516
import java.util.Arrays;
1617
import java.util.Collection;
@@ -22,6 +23,7 @@
2223
import java.util.stream.Collectors;
2324
import javax.lang.model.element.TypeElement;
2425
import javax.lang.model.util.Elements;
26+
2527
import jdk.javadoc.doclet.DocletEnvironment;
2628
import org.apache.commons.lang3.RegExUtils;
2729
import org.junit.Before;
@@ -113,29 +115,29 @@ public void populateUidValues() {
113115
ymlFilesBuilder.populateUidValues(Collections.emptyList(), Arrays.asList(classMetadataFile));
114116

115117
assertThat("Wrong summary for unknown class", item1.getSummary(),
116-
is("Bla bla <xref uid=\"\" data-throw-if-not-resolved=\"false\">UnknownClass</xref> bla"));
118+
is("Bla bla <xref uid=\"\" data-throw-if-not-resolved=\"false\">UnknownClass</xref> bla"));
117119
assertThat("Wrong syntax description", item1.getSyntax().getParameters().get(0).getDescription(),
118-
is("One two <xref uid=\"a.b.SomeClass.someMethod(String param)\" data-throw-if-not-resolved=\"false\">SomeClass#someMethod(String param)</xref> three"));
120+
is("One two <xref uid=\"a.b.SomeClass.someMethod(String param)\" data-throw-if-not-resolved=\"false\">SomeClass#someMethod(String param)</xref> three"));
119121
assertThat("Wrong summary for known class", item2.getSummary(),
120-
is("Bla bla <xref uid=\"a.b.SomeClass.someMethod(String param)\" data-throw-if-not-resolved=\"false\">SomeClass#someMethod(String param)</xref> bla"));
122+
is("Bla bla <xref uid=\"a.b.SomeClass.someMethod(String param)\" data-throw-if-not-resolved=\"false\">SomeClass#someMethod(String param)</xref> bla"));
121123
assertThat("Wrong summary for method", item3.getSummary(),
122-
is("Bla bla <xref uid=\"a.b.OwnerClass.someMethod2(String p1, String p2)\" data-throw-if-not-resolved=\"false\">#someMethod2(String p1, String p2)</xref> bla"));
124+
is("Bla bla <xref uid=\"a.b.OwnerClass.someMethod2(String p1, String p2)\" data-throw-if-not-resolved=\"false\">#someMethod2(String p1, String p2)</xref> bla"));
123125

124126
}
125127

126128
private MetadataFileItem buildMetadataFileItem(String uid, String value) {
127129
MetadataFileItem item = new MetadataFileItem(uid);
128130
item.setSummary(
129-
String.format("Bla bla <xref uid=\"%s\" data-throw-if-not-resolved=\"false\">%s</xref> bla", value, value));
131+
String.format("Bla bla <xref uid=\"%s\" data-throw-if-not-resolved=\"false\">%s</xref> bla", value, value));
130132
return item;
131133
}
132134

133135
private void populateSyntax(MetadataFileItem item, String value) {
134136
Syntax syntax = new Syntax();
135137
String methodParamDescription = String
136-
.format("One two <xref uid=\"%s\" data-throw-if-not-resolved=\"false\">%s</xref> three", value, value);
138+
.format("One two <xref uid=\"%s\" data-throw-if-not-resolved=\"false\">%s</xref> three", value, value);
137139
syntax.setParameters(
138-
Arrays.asList(new MethodParameter("method param id", "method param type", methodParamDescription)));
140+
Arrays.asList(new MethodParameter("method param id", "method param type", methodParamDescription)));
139141
item.setSyntax(syntax);
140142
}
141143

@@ -149,15 +151,15 @@ public void determineUidByLinkContent() {
149151

150152
LookupContext lookupContext = new LookupContext(lookup, lookup);
151153
assertThat("Wrong result for class", ymlFilesBuilder.
152-
resolveUidByLookup("SomeClass", lookupContext), is("a.b.c.SomeClass"));
154+
resolveUidByLookup("SomeClass", lookupContext), is("a.b.c.SomeClass"));
153155
assertThat("Wrong result for method", ymlFilesBuilder.
154-
resolveUidByLookup("SomeClass#someMethod()", lookupContext), is("a.b.c.SomeClass.someMethod()"));
156+
resolveUidFromLinkContent("SomeClass#someMethod()", lookupContext), is("a.b.c.SomeClass.someMethod()"));
155157
assertThat("Wrong result for method with param", ymlFilesBuilder.
156-
resolveUidByLookup("SomeClass#someMethod(String param)", lookupContext),
157-
is("a.b.c.SomeClass.someMethod(String param)"));
158+
resolveUidFromLinkContent("SomeClass#someMethod(String param)", lookupContext),
159+
is("a.b.c.SomeClass.someMethod(String param)"));
158160

159161
assertThat("Wrong result for unknown class", ymlFilesBuilder.
160-
resolveUidByLookup("UnknownClass", lookupContext), is(""));
162+
resolveUidByLookup("UnknownClass", lookupContext), is(""));
161163
assertThat("Wrong result for null", ymlFilesBuilder.resolveUidByLookup(null, lookupContext), is(""));
162164
assertThat("Wrong result for whitespace", ymlFilesBuilder.resolveUidByLookup(" ", lookupContext), is(""));
163165
}
@@ -181,7 +183,7 @@ public void expandComplexGenericsInReferences() {
181183

182184
assertThat("Wrong references amount", references.size(), is(4));
183185
assertThat("Wrong references content",
184-
references.stream().map(MetadataFileItem::getUid).collect(Collectors.toList()),
185-
hasItems("a.b.c.List", "df.mn.ClassOne", "tr.T", "a.b.c.List<df.mn.ClassOne<tr.T>>"));
186+
references.stream().map(MetadataFileItem::getUid).collect(Collectors.toList()),
187+
hasItems("a.b.c.List", "df.mn.ClassOne", "tr.T", "a.b.c.List<df.mn.ClassOne<tr.T>>"));
186188
}
187189
}

0 commit comments

Comments
 (0)