You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flex.apache.org by ms...@apache.org on 2015/06/12 00:43:33 UTC
[2/2] git commit: [flex-falcon] [refs/heads/develop] - Added @param
and @return annotations in emitted .as files with types and descriptions.
Added @param and @return annotations in emitted .as files with types and descriptions.
Project: http://git-wip-us.apache.org/repos/asf/flex-falcon/repo
Commit: http://git-wip-us.apache.org/repos/asf/flex-falcon/commit/59b80b18
Tree: http://git-wip-us.apache.org/repos/asf/flex-falcon/tree/59b80b18
Diff: http://git-wip-us.apache.org/repos/asf/flex-falcon/diff/59b80b18
Branch: refs/heads/develop
Commit: 59b80b18c8cb7196958dd6a1bde97c3d7b87faf0
Parents: 0d09cb3
Author: Michael Schmalle <ms...@apache.org>
Authored: Thu Jun 11 18:42:57 2015 -0400
Committer: Michael Schmalle <ms...@apache.org>
Committed: Thu Jun 11 18:42:57 2015 -0400
----------------------------------------------------------------------
.../codegen/externals/TestConstructor.java | 54 +++++------
.../externals_unit_tests/constructor_params.js | 10 +-
.../externals/reference/BaseReference.java | 99 +++++++++++++++-----
.../externals/reference/FunctionReference.java | 14 +--
.../externals/reference/MemberReference.java | 6 +-
.../externals/reference/MethodReference.java | 11 ++-
6 files changed, 126 insertions(+), 68 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/flex-falcon/blob/59b80b18/compiler.jx.tests/src/org/apache/flex/compiler/internal/codegen/externals/TestConstructor.java
----------------------------------------------------------------------
diff --git a/compiler.jx.tests/src/org/apache/flex/compiler/internal/codegen/externals/TestConstructor.java b/compiler.jx.tests/src/org/apache/flex/compiler/internal/codegen/externals/TestConstructor.java
index 168fee5..973c31e 100644
--- a/compiler.jx.tests/src/org/apache/flex/compiler/internal/codegen/externals/TestConstructor.java
+++ b/compiler.jx.tests/src/org/apache/flex/compiler/internal/codegen/externals/TestConstructor.java
@@ -51,33 +51,33 @@ public class TestConstructor extends ExternalsTestBase
assertEquals(0, FooNoArgs.getConstructor().getParameterNames().size());
assertEquals(2, FooOptArgs.getConstructor().getParameterNames().size());
assertEquals(2, FooVarArgs.getConstructor().getParameterNames().size());
- assertEquals(3,
- FooOptVarArgs.getConstructor().getParameterNames().size());
-
- assertFalse(FooOptArgs.getConstructor().getComment().getParameterType(
- "arg1").isOptionalArg());
- assertTrue(FooOptArgs.getConstructor().getComment().getParameterType(
- "opt_arg2").isOptionalArg());
-
- assertFalse(FooVarArgs.getConstructor().getComment().getParameterType(
- "arg1").isVarArgs());
- assertTrue(FooVarArgs.getConstructor().getComment().getParameterType(
- "var_args").isVarArgs());
-
- assertTrue(FooOptVarArgs.getConstructor().getComment().getParameterType(
- "opt_arg2").isOptionalArg());
- assertTrue(FooOptVarArgs.getConstructor().getComment().getParameterType(
- "var_args").isVarArgs());
-
- assertEquals(
- "number",
- evaluateParam(FooOptVarArgs.getConstructor(), "arg1").toAnnotationString());
- assertEquals(
- "*",
- evaluateParam(FooOptVarArgs.getConstructor(), "opt_arg2").toAnnotationString());
- assertEquals(
- "*",
- evaluateParam(FooOptVarArgs.getConstructor(), "var_args").toAnnotationString());
+ assertEquals(3, FooOptVarArgs.getConstructor().getParameterNames().size());
+
+ assertFalse(FooOptArgs.getConstructor().getComment().getParameterType("arg1").isOptionalArg());
+ assertTrue(FooOptArgs.getConstructor().getComment().getParameterType("opt_arg2").isOptionalArg());
+
+ assertFalse(FooVarArgs.getConstructor().getComment().getParameterType("arg1").isVarArgs());
+ assertTrue(FooVarArgs.getConstructor().getComment().getParameterType("var_args").isVarArgs());
+
+ assertTrue(FooOptVarArgs.getConstructor().getComment().getParameterType("opt_arg2").isOptionalArg());
+ assertTrue(FooOptVarArgs.getConstructor().getComment().getParameterType("var_args").isVarArgs());
+
+ assertEquals("number", evaluateParam(FooOptVarArgs.getConstructor(), "arg1").toAnnotationString());
+ assertEquals("*", evaluateParam(FooOptVarArgs.getConstructor(), "opt_arg2").toAnnotationString());
+ assertEquals("*", evaluateParam(FooOptVarArgs.getConstructor(), "var_args").toAnnotationString());
+ }
+
+ @Test
+ public void test_constructor_comment() throws IOException
+ {
+ compile("constructor_params.js");
+
+ StringBuilder sb = new StringBuilder();
+
+ ClassReference FooOptVarArgs = model.getClassReference("FooOptVarArgs");
+ FooOptVarArgs.getConstructor().emit(sb);
+ String string = sb.toString();
+ assertEquals(" /**\n * A constructor with arg, opt arg and var args.\n *\n * @param arg1 [number] The arg 1.\n * @param opt_arg2 [*] The arg that is wrapped by another line in the comment.\n * @param var_args [*] A var agr param.\n * @see http://foo.bar.com \n * @see [constructor_params]\n * @returns {(FooVarArgs|null)} Another instance.\n */\n native public function FooOptVarArgs(arg1:Number, opt_arg2:* = null, ...rest);\n", string);
}
@Override
http://git-wip-us.apache.org/repos/asf/flex-falcon/blob/59b80b18/compiler.jx.tests/test-files/externals_unit_tests/constructor_params.js
----------------------------------------------------------------------
diff --git a/compiler.jx.tests/test-files/externals_unit_tests/constructor_params.js b/compiler.jx.tests/test-files/externals_unit_tests/constructor_params.js
index fb0fad6..87a1254 100644
--- a/compiler.jx.tests/test-files/externals_unit_tests/constructor_params.js
+++ b/compiler.jx.tests/test-files/externals_unit_tests/constructor_params.js
@@ -46,9 +46,13 @@ function FooVarArgs(arg1, var_args) {}
* A constructor with arg, opt arg and var args.
*
* @constructor
- * @param {number} arg1
- * @param {*=} opt_arg2
- * @param {...*} var_args
+ * @param {number} arg1 The arg 1.
+ * @param {*=} opt_arg2 The arg that is
+ * wrapped by another
+ * line in the comment.
+ * @param {...*} var_args A var agr param.
+ * @see http://foo.bar.com
+ * @returns {FooVarArgs} Another instance.
*/
function FooOptVarArgs(arg1, opt_arg2, var_args) {}
http://git-wip-us.apache.org/repos/asf/flex-falcon/blob/59b80b18/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/BaseReference.java
----------------------------------------------------------------------
diff --git a/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/BaseReference.java b/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/BaseReference.java
index d432461..7c9de3a 100644
--- a/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/BaseReference.java
+++ b/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/BaseReference.java
@@ -20,6 +20,7 @@
package org.apache.flex.compiler.internal.codegen.externals.reference;
import java.io.File;
+import java.util.Set;
import org.apache.flex.compiler.clients.ExternCConfiguration.ExcludedMemeber;
@@ -28,6 +29,7 @@ import com.google.javascript.rhino.JSDocInfo;
import com.google.javascript.rhino.JSDocInfo.Marker;
import com.google.javascript.rhino.JSDocInfo.StringPosition;
import com.google.javascript.rhino.JSDocInfo.TypePosition;
+import com.google.javascript.rhino.JSTypeExpression;
import com.google.javascript.rhino.Node;
public abstract class BaseReference
@@ -111,8 +113,7 @@ public abstract class BaseReference
return model;
}
- public BaseReference(ReferenceModel model, Node node, String qualfiedName,
- JSDocInfo comment)
+ public BaseReference(ReferenceModel model, Node node, String qualfiedName, JSDocInfo comment)
{
this.model = model;
this.node = node;
@@ -123,7 +124,19 @@ public abstract class BaseReference
public void printComment(StringBuilder sb)
{
sb.append(" /**\n");
+ emitCommentBody(sb);
+ sb.append(" */\n");
+ }
+
+ protected void emitCommentBody(StringBuilder sb)
+ {
+ emitBlockDescription(sb);
+ emitSee(sb);
+ emitSeeSourceFileName(sb);
+ }
+ protected void emitBlockDescription(StringBuilder sb)
+ {
String blockDescription = getComment().getBlockDescription();
if (blockDescription != null)
{
@@ -132,6 +145,10 @@ public abstract class BaseReference
sb.append("\n *\n");
}
+ }
+
+ protected void emitSee(StringBuilder sb)
+ {
for (Marker marker : getComment().getMarkers())
{
StringPosition name = marker.getAnnotation();
@@ -164,9 +181,11 @@ public abstract class BaseReference
sb.append(" * @" + desc.toString() + "\n");
}
+ }
+ protected void emitSeeSourceFileName(StringBuilder sb)
+ {
sb.append(" * @see " + getNode().getSourceFileName() + "\n");
- sb.append(" */\n");
}
public ExcludedMemeber isExcluded()
@@ -176,25 +195,57 @@ public abstract class BaseReference
public abstract void emit(StringBuilder sb);
- // public DocletTag findDocTagByName(String tagName)
- // {
- // for (DocletTag tag : getComment().getTags())
- // {
- // if (tag.getName().equals(tagName))
- // {
- // return tag;
- // }
- // }
- // return null;
- // }
- //
- // public boolean hasTag(String tagName)
- // {
- // for (DocletTag tag : getComment().getTags())
- // {
- // if (tag.getName().equals(tagName))
- // return true;
- // }
- // return false;
- // }
+ protected void emitFunctionCommentBody(StringBuilder sb)
+ {
+ emitBlockDescription(sb);
+ emitParams(sb);
+ emitSee(sb);
+ emitSeeSourceFileName(sb);
+ emitReturns(sb);
+ }
+
+ protected void emitParams(StringBuilder sb)
+ {
+ Set<String> parameterNames = getComment().getParameterNames();
+ for (String paramName : parameterNames)
+ {
+ JSTypeExpression parameterType = getComment().getParameterType(paramName);
+ String description = getComment().getDescriptionForParameter(paramName);
+ sb.append(" * @param ");
+
+ sb.append(paramName);
+ sb.append(" ");
+
+ if (parameterType != null)
+ {
+ sb.append("[");
+ sb.append(parameterType.evaluate(null, getModel().getCompiler().getTypeRegistry()).toAnnotationString());
+ sb.append("]");
+ sb.append(" ");
+ }
+ if (description != null)
+ sb.append(description);
+ sb.append("\n");
+ }
+ }
+
+ protected void emitReturns(StringBuilder sb)
+ {
+ if (getComment().hasReturnType())
+ {
+ JSTypeExpression returnType = getComment().getReturnType();
+ if (returnType != null)
+ {
+ sb.append(" * @returns ");
+ sb.append("{");
+ sb.append(returnType.evaluate(null, getModel().getCompiler().getTypeRegistry()).toAnnotationString());
+ sb.append("} ");
+ String description = getComment().getReturnDescription();
+ if (description != null)
+ sb.append(description);
+ sb.append("\n");
+ }
+
+ }
+ }
}
http://git-wip-us.apache.org/repos/asf/flex-falcon/blob/59b80b18/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/FunctionReference.java
----------------------------------------------------------------------
diff --git a/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/FunctionReference.java b/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/FunctionReference.java
index 2c0f695..3d28781 100644
--- a/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/FunctionReference.java
+++ b/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/FunctionReference.java
@@ -37,8 +37,7 @@ public class FunctionReference extends BaseReference
{
String packageName = "";
- return new File(asSourceRoot, packageName + File.separator
- + getQualifiedName() + ".as");
+ return new File(asSourceRoot, packageName + File.separator + getQualifiedName() + ".as");
}
private FunctionReference getContext()
@@ -65,8 +64,7 @@ public class FunctionReference extends BaseReference
BLOCK
*/
- public FunctionReference(ReferenceModel model, Node node,
- String qualifiedName, JSDocInfo comment)
+ public FunctionReference(ReferenceModel model, Node node, String qualifiedName, JSDocInfo comment)
{
super(model, node, qualifiedName, comment);
this.paramNode = node.getChildAtIndex(1);
@@ -132,8 +130,7 @@ public class FunctionReference extends BaseReference
private String toPrameterString()
{
- return FunctionUtils.toPrameterString(getContext(), getComment(),
- paramNode);
+ return FunctionUtils.toPrameterString(getContext(), getComment(), paramNode);
}
public boolean isOverride()
@@ -141,4 +138,9 @@ public class FunctionReference extends BaseReference
return getComment().isOverride();
}
+ @Override
+ protected void emitCommentBody(StringBuilder sb)
+ {
+ emitFunctionCommentBody(sb);
+ }
}
http://git-wip-us.apache.org/repos/asf/flex-falcon/blob/59b80b18/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/MemberReference.java
----------------------------------------------------------------------
diff --git a/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/MemberReference.java b/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/MemberReference.java
index b73afbe..04759b6 100644
--- a/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/MemberReference.java
+++ b/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/MemberReference.java
@@ -34,8 +34,7 @@ public abstract class MemberReference extends BaseReference
return classReference;
}
- public MemberReference(ReferenceModel model, ClassReference classReference,
- Node node, String name, JSDocInfo comment)
+ public MemberReference(ReferenceModel model, ClassReference classReference, Node node, String name, JSDocInfo comment)
{
super(model, node, name, comment);
this.classReference = classReference;
@@ -44,8 +43,7 @@ public abstract class MemberReference extends BaseReference
@Override
public ExcludedMemeber isExcluded()
{
- return getClassReference().getModel().isExcludedMember(
- getClassReference(), this);
+ return getClassReference().getModel().isExcludedMember(getClassReference(), this);
}
}
http://git-wip-us.apache.org/repos/asf/flex-falcon/blob/59b80b18/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/MethodReference.java
----------------------------------------------------------------------
diff --git a/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/MethodReference.java b/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/MethodReference.java
index e194f64..155bb45 100644
--- a/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/MethodReference.java
+++ b/compiler.jx/src/org/apache/flex/compiler/internal/codegen/externals/reference/MethodReference.java
@@ -54,8 +54,7 @@ public class MethodReference extends MemberReference
this.isStatic = isStatic;
}
- public MethodReference(ReferenceModel model, ClassReference classReference,
- Node node, String name, JSDocInfo comment, boolean isStatic)
+ public MethodReference(ReferenceModel model, ClassReference classReference, Node node, String name, JSDocInfo comment, boolean isStatic)
{
super(model, classReference, node, name, comment);
this.isStatic = isStatic;
@@ -163,8 +162,7 @@ public class MethodReference extends MemberReference
private String toPrameterString()
{
- return FunctionUtils.toPrameterString(getContext(), getComment(),
- paramNode);
+ return FunctionUtils.toPrameterString(getContext(), getComment(), paramNode);
}
public boolean isOverride()
@@ -172,4 +170,9 @@ public class MethodReference extends MemberReference
return getComment().isOverride();
}
+ @Override
+ protected void emitCommentBody(StringBuilder sb)
+ {
+ emitFunctionCommentBody(sb);
+ }
}