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 <[email protected]> Authored: Thu Jun 11 18:42:57 2015 -0400 Committer: Michael Schmalle <[email protected]> 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); + } }
