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

Commit d2cd520

Browse files
anmeng10101anmeng10101
authored
convert outputs to schema-driven-processor based yaml files (#51)
* refine memory cache model as pre-step for generating SDP based yaml * add SDP models * fix comment * write SDP based content files and toc to disk * refine test cases and expected results * using double quotes to make sure some Java key words will be handled as string in docs build when they are uses as "name" or "description" * resolve the {@link} in members summary * sort items in toc.yml * sort every level of toc.yml (#50)
1 parent efc79d0 commit d2cd520

163 files changed

Lines changed: 3884 additions & 4469 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎pom.xml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
<apache.commons-lang.version>3.8.1</apache.commons-lang.version>
1818
<apache.commons-collections.version>4.2</apache.commons-collections.version>
1919
<apache.commons-io.version>2.6</apache.commons-io.version>
20+
<apache.commons-text.version>1.9</apache.commons-text.version>
2021
<remark.version>1.1.0</remark.version>
2122
</properties>
2223

@@ -111,6 +112,11 @@
111112
<artifactId>commons-io</artifactId>
112113
<version>${apache.commons-io.version}</version>
113114
</dependency>
115+
<dependency>
116+
<groupId>org.apache.commons</groupId>
117+
<artifactId>commons-text</artifactId>
118+
<version>${apache.commons-text.version}</version>
119+
</dependency>
114120
<dependency>
115121
<groupId>com.fasterxml.jackson.core</groupId>
116122
<artifactId>jackson-databind</artifactId>

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

Lines changed: 77 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
import com.microsoft.lookup.ClassLookup;
66
import com.microsoft.lookup.PackageLookup;
77
import com.microsoft.model.*;
8+
import com.microsoft.model.sdp.file.*;
89
import com.microsoft.util.ElementUtil;
910
import com.microsoft.util.FileUtil;
1011
import com.microsoft.util.Utils;
@@ -75,21 +76,27 @@ public boolean build() {
7576

7677
populateUidValues(packageMetadataFiles, classMetadataFiles);
7778

78-
packageMetadataFiles.forEach(FileUtil::dumpToFile);
79-
classMetadataFiles.forEach(FileUtil::dumpToFile);
79+
// write content files
80+
packageMetadataFiles.forEach(YmlFilesBuilder::writePackageContentToYml);
81+
for (MetadataFile type : classMetadataFiles)
82+
{
83+
writeTypeContentToYml(type);
84+
}
85+
86+
// write toc.yml
8087
FileUtil.dumpToFile(tocFile);
8188

8289
return true;
8390
}
8491

85-
void buildFilesForInnerClasses(Element element, List<TocItem> listToAddItems, List<MetadataFile> container) {
92+
void buildFilesForInnerClasses(Element element, Set<TocItem> listToAddItems, List<MetadataFile> container) {
8693
for (TypeElement classElement : elementUtil.extractSortedElements(element)) {
8794
String uid = classLookup.extractUid(classElement);
8895
String name = classLookup.extractTocName(classElement);
96+
TocItem tocNode = new TocItem(uid, name);
8997

90-
listToAddItems.add(new TocItem(uid, name));
91-
92-
container.add(buildClassYmlFile(classElement));
98+
container.add(buildClassYmlFile(classElement, tocNode));
99+
listToAddItems.add(tocNode);
93100
buildFilesForInnerClasses(classElement, listToAddItems, container);
94101
}
95102
}
@@ -105,12 +112,12 @@ MetadataFile buildPackageMetadataFile(PackageElement packageElement) {
105112
return packageMetadataFile;
106113
}
107114

108-
void addChildrenReferences(Element element, List<String> packageChildren,
115+
void addChildrenReferences(Element element, List<MetadataFileItem> packageChildren,
109116
Set<MetadataFileItem> referencesCollector) {
110117
for (TypeElement classElement : elementUtil.extractSortedElements(element)) {
111118
referencesCollector.add(buildClassReference(classElement));
112119

113-
packageChildren.add(classLookup.extractUid(classElement));
120+
packageChildren.add(classLookup.extractItem(classElement));
114121
addChildrenReferences(classElement, packageChildren, referencesCollector);
115122
}
116123
}
@@ -132,13 +139,13 @@ <T extends Element> void populateItemFields(MetadataFileItem item, BaseLookup<T>
132139
item.setContent(lookup.extractContent(element));
133140
}
134141

135-
MetadataFile buildClassYmlFile(TypeElement classElement) {
142+
MetadataFile buildClassYmlFile(TypeElement classElement, TocItem tocItem) {
136143
String fileName = classLookup.extractHref(classElement);
137144
MetadataFile classMetadataFile = new MetadataFile(outputPath, fileName);
138145
addClassInfo(classElement, classMetadataFile);
139-
addConstructorsInfo(classElement, classMetadataFile);
140-
addMethodsInfo(classElement, classMetadataFile);
141-
addFieldsInfo(classElement, classMetadataFile);
146+
addConstructorsInfo(classElement, classMetadataFile, tocItem);
147+
addMethodsInfo(classElement, classMetadataFile, tocItem);
148+
addFieldsInfo(classElement, classMetadataFile, tocItem);
142149
addReferencesInfo(classElement, classMetadataFile);
143150
applyPostProcessing(classMetadataFile);
144151
return classMetadataFile;
@@ -158,28 +165,28 @@ void addClassInfo(TypeElement classElement, MetadataFile classMetadataFile) {
158165
classMetadataFile.getItems().add(classItem);
159166
}
160167

161-
void addChildren(TypeElement classElement, List<String> children) {
162-
collect(classElement, children, ElementFilter::constructorsIn, classItemsLookup::extractUid);
163-
collect(classElement, children, ElementFilter::methodsIn, classItemsLookup::extractUid);
164-
collect(classElement, children, ElementFilter::fieldsIn, classItemsLookup::extractUid);
165-
collect(classElement, children, ElementFilter::typesIn, String::valueOf);
168+
void addChildren(TypeElement classElement, List<MetadataFileItem> children) {
169+
collect(classElement, children, ElementFilter::constructorsIn, classItemsLookup::extractItem);
170+
collect(classElement, children, ElementFilter::methodsIn, classItemsLookup::extractItem);
171+
collect(classElement, children, ElementFilter::fieldsIn, classItemsLookup::extractItem);
172+
collect(classElement, children, ElementFilter::typesIn, classItemsLookup::extractItem);
166173
}
167174

168175
List<? extends Element> filterPrivateElements(List<? extends Element> elements) {
169176
return elements.stream()
170177
.filter(element -> !Utils.isPrivateOrPackagePrivate(element)).collect(Collectors.toList());
171178
}
172179

173-
void collect(TypeElement classElement, List<String> children,
180+
void collect(TypeElement classElement, List<MetadataFileItem> children,
174181
Function<Iterable<? extends Element>, List<? extends Element>> selectFunc,
175-
Function<? super Element, String> mapFunc) {
182+
Function<? super Element, MetadataFileItem> mapFunc) {
176183

177184
List<? extends Element> elements = selectFunc.apply(classElement.getEnclosedElements());
178185
children.addAll(filterPrivateElements(elements).stream()
179186
.map(mapFunc).collect(Collectors.toList()));
180187
}
181188

182-
void addConstructorsInfo(TypeElement classElement, MetadataFile classMetadataFile) {
189+
void addConstructorsInfo(TypeElement classElement, MetadataFile classMetadataFile, TocItem tocItem) {
183190
for (ExecutableElement constructorElement : ElementFilter.constructorsIn(classElement.getEnclosedElements())) {
184191
MetadataFileItem constructorItem = buildMetadataFileItem(constructorElement);
185192
constructorItem.setOverload(classItemsLookup.extractOverload(constructorElement));
@@ -189,10 +196,15 @@ void addConstructorsInfo(TypeElement classElement, MetadataFile classMetadataFil
189196

190197
addParameterReferences(constructorItem, classMetadataFile);
191198
addOverloadReferences(constructorItem, classMetadataFile);
199+
200+
if(!classElement.getKind().equals(ElementKind.ENUM)){
201+
tocItem.getItems().add(
202+
new TocItem(constructorItem.getOverload(), constructorItem.getShortName(), constructorItem.getType().toLowerCase()));
203+
}
192204
}
193205
}
194206

195-
void addMethodsInfo(TypeElement classElement, MetadataFile classMetadataFile) {
207+
void addMethodsInfo(TypeElement classElement, MetadataFile classMetadataFile, TocItem tocItem) {
196208
ElementFilter.methodsIn(classElement.getEnclosedElements()).stream()
197209
.filter(methodElement -> !Utils.isPrivateOrPackagePrivate(methodElement))
198210
.forEach(methodElement -> {
@@ -209,10 +221,15 @@ void addMethodsInfo(TypeElement classElement, MetadataFile classMetadataFile) {
209221
addParameterReferences(methodItem, classMetadataFile);
210222
addReturnReferences(methodItem, classMetadataFile);
211223
addOverloadReferences(methodItem, classMetadataFile);
224+
225+
if(!classElement.getKind().equals(ElementKind.ENUM)){
226+
tocItem.getItems().add(
227+
new TocItem(methodItem.getOverload(), methodItem.getShortName(), methodItem.getType().toLowerCase()));
228+
}
212229
});
213230
}
214231

215-
void addFieldsInfo(TypeElement classElement, MetadataFile classMetadataFile) {
232+
void addFieldsInfo(TypeElement classElement, MetadataFile classMetadataFile,TocItem tocItem) {
216233
ElementFilter.fieldsIn(classElement.getEnclosedElements()).stream()
217234
.filter(fieldElement -> !Utils.isPrivateOrPackagePrivate(fieldElement))
218235
.forEach(fieldElement -> {
@@ -221,6 +238,11 @@ void addFieldsInfo(TypeElement classElement, MetadataFile classMetadataFile) {
221238
fieldItem.setReturn(classItemsLookup.extractReturn(fieldElement));
222239
classMetadataFile.getItems().add(fieldItem);
223240
addReturnReferences(fieldItem, classMetadataFile);
241+
242+
if(classElement.getKind() != ElementKind.ENUM) {
243+
tocItem.getItems().add(
244+
new TocItem(fieldItem.getUid(), fieldItem.getName(), fieldItem.getType().toLowerCase()));
245+
}
224246
});
225247
}
226248

@@ -307,6 +329,33 @@ void applyPostProcessing(MetadataFile classMetadataFile) {
307329
expandComplexGenericsInReferences(classMetadataFile);
308330
}
309331

332+
private static void writePackageContentToYml(MetadataFile pack) {
333+
for (MetadataFileItem item : pack.getItems()) {
334+
PackageModel model = new PackageModel(item, pack.getFileNameWithPath());;
335+
FileUtil.dumpToFile(model);
336+
}
337+
}
338+
339+
private void writeTypeContentToYml(MetadataFile typeItem) {
340+
MetadataFileItem item = typeItem.getItems().iterator().next();
341+
String type = item.getType();
342+
switch (type.toLowerCase()) {
343+
case "class":
344+
case "interface":
345+
TypeModel typeModel = new TypeModel(item, typeItem.getFileNameWithPath(), getOutputPath());
346+
FileUtil.dumpToFile(typeModel);
347+
break;
348+
case "enum":
349+
EnumModel enumModel = new EnumModel(item, typeItem.getFileNameWithPath());
350+
FileUtil.dumpToFile(enumModel);
351+
break;
352+
}
353+
}
354+
355+
public String getOutputPath() {
356+
return outputPath;
357+
}
358+
310359
/**
311360
* Replace one record in 'references' with several records in this way:
312361
* <pre>
@@ -346,6 +395,12 @@ void populateUidValues(List<MetadataFile> packageMetadataFiles, List<MetadataFil
346395
populateUidValues(item.getSummary(), lookupContext)
347396
));
348397

398+
for(MetadataFileItem child :item.getChildren()) {
399+
child.setSummary(YamlUtil.convertHtmlToMarkdown(
400+
populateUidValues(child.getSummary(), lookupContext)
401+
));
402+
}
403+
349404
Optional.ofNullable(item.getSyntax()).ifPresent(syntax -> {
350405
Optional.ofNullable(syntax.getParameters()).ifPresent(
351406
methodParams -> methodParams.forEach(

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,10 @@ protected BaseLookup(DocletEnvironment environment) {
4545
this.environment = environment;
4646
}
4747

48+
public ExtendedMetadataFileItem extractItem(T key) {
49+
return resolve(key);
50+
}
51+
4852
protected ExtendedMetadataFileItem resolve(T key) {
4953
ExtendedMetadataFileItem value = map.get(key);
5054
if (value == null) {

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

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
import com.microsoft.model.ExceptionItem;
66
import com.microsoft.model.MethodParameter;
7+
import com.microsoft.model.Field;
78
import com.microsoft.model.Return;
89

910
import com.microsoft.util.CommentHelper;
@@ -81,7 +82,7 @@ protected ExtendedMetadataFileItem buildMetadataFileItem(Element element) {
8182
if (element instanceof VariableElement) {
8283
String type = makeTypeShort(String.valueOf(element.asType()));
8384
result.setFieldContent(String.format("%s %s %s", modifiers, type, elementQName));
84-
result.setReturn(extractReturn((VariableElement) element));
85+
result.setField(extractField((VariableElement) element));
8586
}
8687
return result;
8788
}
@@ -154,6 +155,11 @@ String extractOverriddenUid(ExecutableElement ovr) {
154155
return "";
155156
}
156157

158+
public Field extractField(VariableElement fieldElement) {
159+
var constantValue = (null == fieldElement.getConstantValue()) ? null : fieldElement.getConstantValue().toString();
160+
return new Field(String.valueOf(fieldElement.asType()), constantValue);
161+
}
162+
157163
/**
158164
* If the item being inherited from is declared from external compiled package,
159165
* or is declared in the packages like java.lang.Object,

‎src/main/java/com/microsoft/lookup/model/ExtendedMetadataFileItem.java‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,4 +116,20 @@ public void addReferences(Set<MetadataFileItem> references) {
116116
public Set<MetadataFileItem> getReferences() {
117117
return references;
118118
}
119+
120+
public String getSyntaxContent() {
121+
String content = "";
122+
switch (this.getType().toLowerCase()) {
123+
case "constructor":
124+
content = getConstructorContent();
125+
break;
126+
case "field":
127+
content = getFieldContent();
128+
break;
129+
case "method":
130+
content = getMethodContent();
131+
break;
132+
}
133+
return content;
134+
}
119135
}

‎src/main/java/com/microsoft/model/ExceptionItem.java‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,22 @@
11
package com.microsoft.model;
22

3+
import com.fasterxml.jackson.annotation.JsonIgnore;
4+
import com.fasterxml.jackson.annotation.JsonProperty;
5+
6+
import com.microsoft.util.XrefHelper;
7+
38
public class ExceptionItem {
49

10+
@JsonIgnore
511
private final String type;
12+
@JsonProperty("type")
13+
private String exceptionXrefString;
614
private final String description;
715

816
public ExceptionItem(String type, String description) {
917
this.type = type;
1018
this.description = description;
19+
this.exceptionXrefString = XrefHelper.generateXrefString(type, XrefHelper.XrefOption.SHORTNAME);
1120
}
1221

1322
public String getType() {
@@ -17,4 +26,8 @@ public String getType() {
1726
public String getDescription() {
1827
return description;
1928
}
29+
30+
public String getExceptionXrefString() {
31+
return exceptionXrefString;
32+
}
2033
}

‎src/main/java/com/microsoft/model/Field.java‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
package com.microsoft.model;
2+
3+
import com.fasterxml.jackson.annotation.JsonIgnore;
4+
import com.fasterxml.jackson.annotation.JsonProperty;
5+
import com.microsoft.util.XrefHelper;
6+
7+
public class Field {
8+
9+
@JsonIgnore
10+
private final String fieldType;
11+
@JsonProperty("description")
12+
private String fieldDescription;
13+
@JsonProperty("type")
14+
private String fieldXrefString;
15+
private String value;
16+
17+
public String getFieldDescription() {
18+
return fieldDescription;
19+
}
20+
21+
public String getFieldXrefString() {
22+
return fieldXrefString;
23+
}
24+
25+
public String getValue() {
26+
return value;
27+
}
28+
29+
public Field(String fieldType, String value) {
30+
this.fieldType = fieldType;
31+
this.value = value ;
32+
this.fieldXrefString = XrefHelper.generateXrefString(fieldType, XrefHelper.XrefOption.SHORTNAME);
33+
}
34+
}

‎src/main/java/com/microsoft/model/MetadataFile.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ public Set<MetadataFileItem> getReferences() {
3232
public String getFileContent() {
3333
Set<MetadataFileItem> sortedSet = new TreeSet<>(this.items);
3434
this.items = sortedSet;
35-
return METADATA_FILE_HEADER + YamlUtil.objectToYamlString(this);
35+
return METADATA_FILE_HEADER + YamlUtil.objectToYamlString(this, this.fileName);
3636
}
3737

3838
@JsonIgnore

0 commit comments

Comments
 (0)