This is an automated email from the ASF dual-hosted git repository.
Harbs pushed a commit to branch codegraph
in repository https://gitbox.apache.org/repos/asf/royale-compiler.git
The following commit(s) were added to refs/heads/codegraph by this push:
new 9fd5ae8c1 Add ASDoc support to Code Graph: implement CodeGraphASDoc
and CodeGraphASDocTag classes, update CodeGraphExporter and CodeGraphWriter to
handle ASDoc, and enhance tests for ASDoc integration
9fd5ae8c1 is described below
commit 9fd5ae8c132aa45277efd11d76e8e9bf3a3835e5
Author: Harbs <[email protected]>
AuthorDate: Fri Jul 31 14:37:11 2026 +0300
Add ASDoc support to Code Graph: implement CodeGraphASDoc and
CodeGraphASDocTag classes, update CodeGraphExporter and CodeGraphWriter to
handle ASDoc, and enhance tests for ASDoc integration
---
.../apache/royale/compiler/clients/CODEGRAPH.java | 4 ++
.../internal/codegen/graph/CodeGraphASDoc.java | 53 ++++++++++++++++++++++
.../internal/codegen/graph/CodeGraphASDocTag.java | 45 ++++++++++++++++++
.../internal/codegen/graph/CodeGraphExporter.java | 44 ++++++++++++++++++
.../internal/codegen/graph/CodeGraphSymbol.java | 11 +++++
.../internal/codegen/graph/CodeGraphWriter.java | 38 ++++++++++++++++
.../codegen/graph/TestCodeGraphWriter.java | 7 +++
.../test/resources/codegraph/golden/GraphRoot.as | 7 +++
.../test/resources/codegraph/golden/GraphRoot.json | 17 +++++++
9 files changed, 226 insertions(+)
diff --git
a/compiler-jx/src/main/java/org/apache/royale/compiler/clients/CODEGRAPH.java
b/compiler-jx/src/main/java/org/apache/royale/compiler/clients/CODEGRAPH.java
index 0acd3c0c3..d9ab6c39d 100644
---
a/compiler-jx/src/main/java/org/apache/royale/compiler/clients/CODEGRAPH.java
+++
b/compiler-jx/src/main/java/org/apache/royale/compiler/clients/CODEGRAPH.java
@@ -42,6 +42,7 @@ import
org.apache.royale.compiler.problems.InternalCompilerProblem;
import org.apache.royale.compiler.targets.ITarget.TargetType;
import org.apache.royale.compiler.targets.ITargetSettings;
import org.apache.royale.compiler.units.ICompilationUnit;
+import org.apache.royale.compiler.units.requests.ISyntaxTreeRequestResult;
public class CODEGRAPH extends MXMLJSCRoyale
{
@@ -95,12 +96,15 @@ public class CODEGRAPH extends MXMLJSCRoyale
}
Collection<IDefinition> definitions = new ArrayList<IDefinition>();
+ Collection<ISyntaxTreeRequestResult> syntaxTrees = new
ArrayList<ISyntaxTreeRequestResult>();
for (ICompilationUnit compilationUnit :
getReachableCompilationUnits())
{
+ syntaxTrees.add(compilationUnit.getSyntaxTreeRequest().get());
definitions.addAll(compilationUnit.getFileScopeRequest().get().getExternallyVisibleDefinitions());
}
CodeGraphModel model = new
CodeGraphExporter(project).export(definitions, getGraphTarget(), null);
+ syntaxTrees.clear();
File outputFile = getGraphOutputFile();
File parent = outputFile.getParentFile();
if (parent != null && !parent.exists())
diff --git
a/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphASDoc.java
b/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphASDoc.java
new file mode 100644
index 000000000..a674018ae
--- /dev/null
+++
b/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphASDoc.java
@@ -0,0 +1,53 @@
+/*
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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
+ *
+ * http://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 org.apache.royale.compiler.internal.codegen.graph;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Parsed ASDoc content attached directly to a graph symbol.
+ */
+public final class CodeGraphASDoc
+{
+ private final String description;
+ private final List<CodeGraphASDocTag> tags = new
ArrayList<CodeGraphASDocTag>();
+
+ public CodeGraphASDoc(String description)
+ {
+ this.description = description;
+ }
+
+ public String getDescription()
+ {
+ return description;
+ }
+
+ public void addTag(CodeGraphASDocTag tag)
+ {
+ tags.add(tag);
+ }
+
+ public List<CodeGraphASDocTag> getTags()
+ {
+ return Collections.unmodifiableList(tags);
+ }
+}
\ No newline at end of file
diff --git
a/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphASDocTag.java
b/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphASDocTag.java
new file mode 100644
index 000000000..b28084ffb
--- /dev/null
+++
b/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphASDocTag.java
@@ -0,0 +1,45 @@
+/*
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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
+ *
+ * http://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 org.apache.royale.compiler.internal.codegen.graph;
+
+/**
+ * A parsed ASDoc tag attached to a graph symbol.
+ */
+public final class CodeGraphASDocTag
+{
+ private final String name;
+ private final String description;
+
+ public CodeGraphASDocTag(String name, String description)
+ {
+ this.name = name;
+ this.description = description;
+ }
+
+ public String getName()
+ {
+ return name;
+ }
+
+ public String getDescription()
+ {
+ return description;
+ }
+}
\ No newline at end of file
diff --git
a/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphExporter.java
b/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphExporter.java
index eed8e2ca9..7d311568a 100644
---
a/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphExporter.java
+++
b/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphExporter.java
@@ -21,15 +21,19 @@ package org.apache.royale.compiler.internal.codegen.graph;
import java.util.ArrayList;
import java.util.Collection;
+import java.util.Collections;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
+import org.apache.royale.compiler.asdoc.IASDocComment;
+import org.apache.royale.compiler.asdoc.IASDocTag;
import org.apache.royale.compiler.definitions.IClassDefinition;
import org.apache.royale.compiler.definitions.IConstantDefinition;
import org.apache.royale.compiler.definitions.IDefinition;
+import org.apache.royale.compiler.definitions.IDocumentableDefinition;
import org.apache.royale.compiler.definitions.IFunctionDefinition;
import org.apache.royale.compiler.definitions.IGetterDefinition;
import org.apache.royale.compiler.definitions.IInterfaceDefinition;
@@ -85,6 +89,7 @@ public final class CodeGraphExporter
{
CodeGraphSymbol symbol = createSymbol(definition,
getTypeKind(definition));
addMetadata(symbol, definition);
+ addASDoc(symbol, definition);
if (definition instanceof IClassDefinition)
{
IClassDefinition classDefinition = (IClassDefinition)definition;
@@ -141,6 +146,7 @@ public final class CodeGraphExporter
CodeGraphSymbol symbol = new CodeGraphSymbol(id,
definition.getQualifiedName(), definition.getBaseName(),
definition.getPackageName(), kind);
addMetadata(symbol, definition);
+ addASDoc(symbol, definition);
symbol.setDeclaringType(createReference(declaringType));
if (definition instanceof IGetterDefinition || definition instanceof
ISetterDefinition)
{
@@ -187,6 +193,7 @@ public final class CodeGraphExporter
CodeGraphIdFactory.member(declaringType.getQualifiedName(),
definition.getBaseName()),
definition.getQualifiedName(), definition.getBaseName(),
definition.getPackageName(), kind);
addMetadata(symbol, definition);
+ addASDoc(symbol, definition);
symbol.setDeclaringType(createReference(declaringType));
ITypeDefinition typeDefinition = definition.resolveType(project);
if (typeDefinition != null)
@@ -220,6 +227,43 @@ public final class CodeGraphExporter
}
}
+ private void addASDoc(CodeGraphSymbol symbol, IDefinition definition)
+ {
+ if (!(definition instanceof IDocumentableDefinition))
+ return;
+ IASDocComment comment =
((IDocumentableDefinition)definition).getExplicitSourceComment();
+ if (comment == null)
+ return;
+ if (comment.getDescription() == null)
+ comment.compile();
+ CodeGraphASDoc asDoc = new
CodeGraphASDoc(normalizeASDocText(comment.getDescription()));
+ Map<String, List<IASDocTag>> tags = comment.getTags();
+ if (tags != null)
+ {
+ List<String> tagNames = new ArrayList<String>(tags.keySet());
+ Collections.sort(tagNames);
+ for (String tagName : tagNames)
+ {
+ List<IASDocTag> tagValues = tags.get(tagName);
+ if (tagValues == null || tagValues.isEmpty())
+ {
+ asDoc.addTag(new CodeGraphASDocTag(tagName, null));
+ continue;
+ }
+ for (IASDocTag tag : tagValues)
+ asDoc.addTag(new CodeGraphASDocTag(tagName,
normalizeASDocText(tag.getDescription())));
+ }
+ }
+ symbol.setASDoc(asDoc);
+ }
+
+ private String normalizeASDocText(String value)
+ {
+ if (value == null)
+ return null;
+ return value.replace("\\\"", "\"");
+ }
+
private CodeGraphReference createReference(ITypeDefinition definition)
{
String qualifiedName = definition.getQualifiedName();
diff --git
a/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphSymbol.java
b/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphSymbol.java
index ff940c8c5..7c0e84040 100644
---
a/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphSymbol.java
+++
b/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphSymbol.java
@@ -36,6 +36,7 @@ public final class CodeGraphSymbol
private CodeGraphReference type;
private CodeGraphReference returnType;
private CodeGraphReference baseType;
+ private CodeGraphASDoc asDoc;
private final List<CodeGraphReference> interfaces = new
ArrayList<CodeGraphReference>();
private final List<CodeGraphParameter> parameters = new
ArrayList<CodeGraphParameter>();
private final List<CodeGraphMetadata> metadata = new
ArrayList<CodeGraphMetadata>();
@@ -135,6 +136,16 @@ public final class CodeGraphSymbol
this.baseType = baseType;
}
+ public CodeGraphASDoc getASDoc()
+ {
+ return asDoc;
+ }
+
+ public void setASDoc(CodeGraphASDoc asDoc)
+ {
+ this.asDoc = asDoc;
+ }
+
public void addInterface(CodeGraphReference interfaceReference)
{
interfaces.add(interfaceReference);
diff --git
a/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphWriter.java
b/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphWriter.java
index 05d86fc32..22d4b51f0 100644
---
a/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphWriter.java
+++
b/compiler-jx/src/main/java/org/apache/royale/compiler/internal/codegen/graph/CodeGraphWriter.java
@@ -94,6 +94,8 @@ public final class CodeGraphWriter
writeReferenceProperty(writer, level + 1, "returnType",
symbol.getReturnType(), --optionalPropertyCount > 0);
if (symbol.getBaseType() != null)
writeReferenceProperty(writer, level + 1, "baseType",
symbol.getBaseType(), --optionalPropertyCount > 0);
+ if (symbol.getASDoc() != null)
+ writeASDoc(writer, symbol.getASDoc(), level + 1,
--optionalPropertyCount > 0);
if (!symbol.getInterfaces().isEmpty())
{
writeReferences(writer, "interfaces", symbol.getInterfaces(),
level + 1, --optionalPropertyCount > 0);
@@ -127,6 +129,8 @@ public final class CodeGraphWriter
result++;
if (symbol.getBaseType() != null)
result++;
+ if (symbol.getASDoc() != null)
+ result++;
if (!symbol.getInterfaces().isEmpty())
result++;
if (!symbol.getParameters().isEmpty())
@@ -138,6 +142,40 @@ public final class CodeGraphWriter
return result;
}
+ private void writeASDoc(Writer writer, CodeGraphASDoc asDoc, int level,
boolean comma) throws IOException
+ {
+ indent(writer, level);
+ writeString(writer, "asdoc");
+ writer.write(": {\n");
+ writeProperty(writer, level + 1, "description",
asDoc.getDescription(), true);
+ indent(writer, level + 1);
+ writeString(writer, "tags");
+ writer.write(": [");
+ if (!asDoc.getTags().isEmpty())
+ writer.write('\n');
+ for (int i = 0; i < asDoc.getTags().size(); i++)
+ {
+ CodeGraphASDocTag tag = asDoc.getTags().get(i);
+ indent(writer, level + 2);
+ writer.write("{\n");
+ writeProperty(writer, level + 3, "name", tag.getName(), true);
+ writeProperty(writer, level + 3, "description",
tag.getDescription(), false);
+ indent(writer, level + 2);
+ writer.write('}');
+ if (i + 1 < asDoc.getTags().size())
+ writer.write(',');
+ writer.write('\n');
+ }
+ if (!asDoc.getTags().isEmpty())
+ indent(writer, level + 1);
+ writer.write("]\n");
+ indent(writer, level);
+ writer.write('}');
+ if (comma)
+ writer.write(',');
+ writer.write('\n');
+ }
+
private void writeReferenceProperty(Writer writer, int level, String name,
CodeGraphReference reference,
boolean comma) throws IOException
{
diff --git
a/compiler-jx/src/test/java/org/apache/royale/compiler/internal/codegen/graph/TestCodeGraphWriter.java
b/compiler-jx/src/test/java/org/apache/royale/compiler/internal/codegen/graph/TestCodeGraphWriter.java
index 96ce598ae..4ee729549 100644
---
a/compiler-jx/src/test/java/org/apache/royale/compiler/internal/codegen/graph/TestCodeGraphWriter.java
+++
b/compiler-jx/src/test/java/org/apache/royale/compiler/internal/codegen/graph/TestCodeGraphWriter.java
@@ -76,6 +76,10 @@ public class TestCodeGraphWriter
CodeGraphMetadata metadata = new CodeGraphMetadata("DefaultProperty");
metadata.addAttribute(new CodeGraphMetadataAttribute(null, "content"));
owner.addMetadata(metadata);
+ CodeGraphASDoc asDoc = new CodeGraphASDoc("A widget.");
+ asDoc.addTag(new CodeGraphASDocTag("copy", "example.Base#label"));
+ asDoc.addTag(new CodeGraphASDocTag("see", "example.Other"));
+ owner.setASDoc(asDoc);
CodeGraphSymbol method = new
CodeGraphSymbol("as3://example/Widget#work(String)",
"example.Widget.work", "work", "example", "method");
method.setDeclaringType(new CodeGraphReference(owner.getId(),
owner.getQualifiedName(), false, false));
@@ -96,6 +100,9 @@ public class TestCodeGraphWriter
assertTrue(firstOutput.toString().contains("\"members\": ["));
assertTrue(firstOutput.toString().contains("\"parameters\": ["));
assertTrue(firstOutput.toString().contains("\"metadata\": ["));
+ assertTrue(firstOutput.toString().contains("\"asdoc\": {"));
+ assertTrue(firstOutput.toString().contains("\"description\": \"A
widget.\""));
+ assertTrue(firstOutput.toString().contains("\"name\": \"copy\""));
assertTrue(firstOutput.toString().contains("\"key\": null"));
assertTrue(firstOutput.toString().contains("\"external\": true"));
}
diff --git a/compiler-jx/src/test/resources/codegraph/golden/GraphRoot.as
b/compiler-jx/src/test/resources/codegraph/golden/GraphRoot.as
index e7aadf66b..71fba33ed 100644
--- a/compiler-jx/src/test/resources/codegraph/golden/GraphRoot.as
+++ b/compiler-jx/src/test/resources/codegraph/golden/GraphRoot.as
@@ -2,6 +2,13 @@ package codegraph.golden
{
[Event(name="complete", type="codegraph.golden.GraphEvent")]
[DefaultProperty("label")]
+ /**
+ * "Root" graph description.
+ *
+ * @see codegraph.golden.GraphBase
+ * @copy codegraph.golden.GraphBase#label
+ * @see codegraph.golden.IGraphContract
+ */
public class GraphRoot extends GraphBase implements IGraphContract
{
public function GraphRoot(value:String)
diff --git a/compiler-jx/src/test/resources/codegraph/golden/GraphRoot.json
b/compiler-jx/src/test/resources/codegraph/golden/GraphRoot.json
index 7e6118925..728ee60e6 100644
--- a/compiler-jx/src/test/resources/codegraph/golden/GraphRoot.json
+++ b/compiler-jx/src/test/resources/codegraph/golden/GraphRoot.json
@@ -79,6 +79,23 @@
"external": false,
"unresolved": false
},
+ "asdoc": {
+ "description": "\"Root\" graph description.",
+ "tags": [
+ {
+ "name": "copy",
+ "description": "codegraph.golden.GraphBase#label"
+ },
+ {
+ "name": "see",
+ "description": "codegraph.golden.GraphBase"
+ },
+ {
+ "name": "see",
+ "description": "codegraph.golden.IGraphContract"
+ }
+ ]
+ },
"interfaces": [
{
"id": "as3://codegraph/golden/IGraphContract",
