You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@royale.apache.org by gr...@apache.org on 2019/06/27 00:38:51 UTC
[royale-docs] branch master updated: Adding some docs for various
optimization options for javascript. For review by others...
This is an automated email from the ASF dual-hosted git repository.
gregdove pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/royale-docs.git
The following commit(s) were added to refs/heads/master by this push:
new d0a7ee9 Adding some docs for various optimization options for javascript. For review by others...
d0a7ee9 is described below
commit d0a7ee9b60cbeb18665947017117256c0f8c0a4b
Author: greg-dove <gr...@gmail.com>
AuthorDate: Thu Jun 27 12:38:30 2019 +1200
Adding some docs for various optimization options for javascript. For review by others...
---
_data/toc.json | 11 +
build.xml | 21 +-
create-an-Application.md | 3 +
create-an-application/optimizations.md | 35 +++
.../compiler-configuration-settings.md | 163 ++++++++++++++
.../optimizations/doc-comment-directives.md | 243 +++++++++++++++++++++
6 files changed, 474 insertions(+), 2 deletions(-)
diff --git a/_data/toc.json b/_data/toc.json
index 5df2fc3..799d78f 100644
--- a/_data/toc.json
+++ b/_data/toc.json
@@ -157,6 +157,17 @@
},
{
"path": "create-an-application/code-conventions.md"
+ },
+ {
+ "path": "create-an-application/optimizations.md",
+ "children": [
+ {
+ "path": "create-an-application/optimizations/compiler-configuration-settings.md"
+ },
+ {
+ "path": "create-an-application/optimizations/doc-comment-directives.md"
+ }
+ ]
}
]
}
diff --git a/build.xml b/build.xml
index 31109d8..850d2b9 100644
--- a/build.xml
+++ b/build.xml
@@ -25,13 +25,30 @@
<property environment="env"/>
<property file="${basedir}/../local.properties"/>
<property file="${basedir}/../build.properties"/>
-
+ <condition property="jekyll.executable" value="jekyll" else="jekyll.bat" >
+ <not>
+ <os family="windows"/>
+ </not>
+ </condition>
+
+ <property name="launchURL" value="http://127.0.0.1:4000/royale-docs/"/>
+
<target name="main" description="Build everything">
- <exec executable="jekyll" failonerror="true">
+ <exec executable="${jekyll.executable}" failonerror="true">
<arg value="build" />
<arg value="--config" />
<arg value="local_config.yml" />
</exec>
</target>
+ <target name="serve" description="Serve and launch">
+ <!-- this approach/sequence works on windows, needs checking on mac -->
+ <script language="javascript"><![CDATA[
+ var location = project.getProperty("launchURL").toString();
+ java.awt.Desktop.getDesktop().browse(java.net.URI.create(location));
+ ]]></script>
+ <exec executable="${jekyll.executable}" failonerror="true">
+ <arg value="serve" />
+ </exec>
+ </target>
</project>
diff --git a/create-an-Application.md b/create-an-Application.md
index b8f1a98..ba1d02f 100644
--- a/create-an-Application.md
+++ b/create-an-Application.md
@@ -36,3 +36,6 @@ This document is divided into several sections:
[Modules](create-an-application/modules.html) discusses how to break your application into pieces so it doesn't have to all get downloaded at once. Or have the whole thing compiled at once.
[Royale code conventions](create-an-application/code-conventions.html) explains the typical ways Royale developers name files, classes, function, variables and more.
+
+[Optimizations](create-an-application/optimizations.html) explains some of the compiler settings and in-code doc comment directives that can be used to tune the output of javascript that Royale generates.
+
diff --git a/create-an-application/optimizations.md b/create-an-application/optimizations.md
new file mode 100644
index 0000000..5f28067
--- /dev/null
+++ b/create-an-application/optimizations.md
@@ -0,0 +1,35 @@
+---
+# 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.
+
+layout: docpage
+title: Optimizations
+---
+# Optimizations
+
+Warning: This document is a work-in-progress/undergoing review.
+
+## Optimization options
+
+The following content explains optimizations for javascript output that you can use when configuring the Royale compiler directly or by using doc-comment directives in your actionscript code.
+Many settings have corresponding approaches between the over-arching compiler level influence of compilation settings and those with more specificity at the code level, so to avoid repetition, it is recommended that you get familiar with the Compiler settings first.
+
+[Compiler Configuration Settings](create-an-application/optimizations/compiler-configuration-settings.html) These are settings that affect the output of the current compilation based on compiler configuration settings.
+
+[Doc-Comment Compiler Directives](create-an-application/optimizations/doc-comment-directives.html) These are settings that affect the output of the current compilation by using doc-comment compiler directives in your actionscript code.
+
+
+
+
diff --git a/create-an-application/optimizations/compiler-configuration-settings.md b/create-an-application/optimizations/compiler-configuration-settings.md
new file mode 100644
index 0000000..2a00941
--- /dev/null
+++ b/create-an-application/optimizations/compiler-configuration-settings.md
@@ -0,0 +1,163 @@
+---
+# 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.
+
+layout: docpage
+title: Compiler configuration settings
+---
+## (Optimization options)
+# Compiler configuration settings
+
+Warning: This document is a work-in-progress/undergoing review.
+
+Definitions:
+AVM
+: Actionscript Virtual Machine. You can also broadly interpret this to mean 'SWF at runtime', the 'flash player' or 'Adobe AIR runtime'.
+
+The following content explains optimizations for javascript output that you can use when configuring the Royale compiler directly.
+Often these settings involve removing some javascript emulations of runtime type-safety that are present in AVM.
+It can be useful to develop your application with these settings 'on' and then consider 'switching them off' for your release build when you have assured yourself it is safe to do so.
+This can help to improve performance and/or reduce the size of your final application build.
+These settings can be provided on the commandline or via royale-config.xml, or via the additionalOptions tag for compiler in maven's pom.xml.
+
+|[Initialization of default values](create-an-application/optimizations/compiler-configuration-settings.html#default-initializers) |
+|[Implict Coercions of non-primitive types](create-an-application/optimizations/compiler-configuration-settings.html#implicit-complex-coercions) |
+|[Parity for strict equality comparisons](create-an-application/optimizations/compiler-configuration-settings.html#strict-equality-comparisons) |
+|[Vector Index Checking](create-an-application/optimizations/compiler-configuration-settings.html#vector-index-checking) |
+
+* * *
+### Default initializers {#default-initializers}
+#### -js-default-initializers (this setting is true by default)
+
+This corresponds to AVM runtime implicit type intialization values, in particular for primitive types.
+Note that some reflection utility functions require this to be true in order for them to work correctly in javascript.
+
+>Todo: This content is yet to be created
+
+
+
+* * *
+### Implict Coercions of non-primitive types {#implicit-complex-coercions}
+#### -js-complex-implicit-coercions (this setting is true by default)
+
+This corresponds to AVM runtime implicit type coercions for non-primitive types (anything that is not a Number, int, uint, String, Boolean) and is not being cast to something that is untyped (__*__ type) or loosely typed, e.g. of **Object** type.
+
+An (overly simplistic) example would be:
+```actionscript
+var cat:Cat = new Cat();
+var myCats:Array = [cat];
+//from this point on, array access of index 0 in myCats
+//represents an unknown type (from the compiler's perspective)
+//in AVM, the following would always cause a runtime error
+//unless Cat was a subclass of Dog, which we will assume it is not!
+var dog:Dog = myCats[0];
+```
+
+With *-js-complex-implicit-coercions=true* (the default setting), the above example will behave the same in javascript at runtime as it would in AVM.
+However supporting this runtime behavior does generate extra type-checking code to achieve that result.
+In most cases this extra code can be eliminated in the output after the application has been validated to be error-free at runtime.
+There may however be cases with legacy actionscript that depend on error-handling for these situations and where refactoring that aspect is not a priority.
+In these cases it can be left on in the release build, or there is also the option to switch it off in general but force it to remain on for specific code scope, for example, using [@royalesuppresscompleximplicitcoercion](create-an-application/optimizations/doc-comment-directives.html#royalesuppresscompleximplicitcoercion).
+
+Does this feature always catch implicit complex coercions?
+No, currently there can still be cases which are missing this level of runtime type safety.
+Notably this can occur in the processing of mxml instances or binding support.
+
+#### Pro tip:
+How do I know how much of my code is being affected by this setting?
+In the javascript **js‑debug** output, you can do a ***search in files*** for the string **/* implicit cast */** which precedes the compiler-generated code the to support this parity with AVM.
+That will show you all the sites where it is being output. As with all other code, this can be minimized in the js-release output, but as mentioned earlier, if the application does not have runtime errors, then the performance of the application could be optimized by eliminating these checks.
+
+* * *
+### Parity for strict equality comparisons {#strict-equality-comparisons}
+#### -js-resolve-uncertain (this setting is true by default)
+
+This is a relatively rare as3 language parity feature that is applied by the compiler when instantiating an unknown class.
+It ensures greater compatibility between AVM and javascript, in particular for strict equality comparisons.
+This is not just important for the binary operators like `===` or `!==`, but also for things like `Array.indexOf`, which uses strict equality for checking.
+
+An (overly simplistic) example would be:
+```actionscript
+var clazz:Class = String;
+var test:Array = ['test', new clazz(30.5)];
+//in AVM, the above would result in: ['test', '30.5']
+var idx:int = test.indexOf('30.5');
+//with js-resolve-uncertain=true idx will be 1 above (correct)
+//in javscript, with js-resolve-uncertain=false, it would be -1 (incorrect)
+```
+
+In most cases this setting is probably not going to cause performance issues. But it does add a small amount of extra overhead in both size and performance.
+The main variations to cover are the primitive types: **Number**, **String**, **Boolean** etc., as well as synthetic types for **int** and **uint**.
+So it can be switched off if after testing it is deemed safe to do so.
+Or it can be specifically avoided or explicitly switched on in specific areas of code with [@royalesuppressresolveuncertain](create-an-application/optimizations/doc-comment-directives.html#royalesuppressresolveuncertain).
+
+***Pro tip:***
+How do I know how much of my code is being affected by this setting?
+In javascript the **js‑debug** output, you can do a ***search in files*** for the string **Language.resolveUncertain**
+* * *
+
+### Vector index checking {#vector-index-checking}
+#### -js-vector-index-checks (this setting is true by default)
+This corresponds to AVM runtime checking during Vector index assignments (*note:* currently only for assignment, not access)
+
+An (overly simplistic) example would be:
+```actionscript
+var myVec:Vector.<Number> = new Vector.<Number>();
+myVec[1] = 2;
+//the above will generate a runtime error in AVM,
+//because Vectors must have contiguous index ranges.
+//In this case the length is zero, and the first assignment
+//can only be made to index 0, not index 1.
+```
+
+or:
+```actionscript
+myVec = new Vector.<Number>(20,true); //create a fixed length Vector, with indices 0 to 19.
+myVec[20] = 2;
+//the above will generate a runtime error in AVM,
+//because you cannot use an index beyond the permitted range
+//of fixed Vectors.
+//In this case the length is 20, and the only assignment can be to indices 0 to 19
+```
+
+With *-js-vector-index-checks=true* (the default setting), the above 2 examples will behave the same in javascript at runtime as they would in AVM and in both cases generate a runtime error.
+However supporting this runtime behavior does generate extra code to achieve that result.
+In most cases it could be avoided to assist with performance. This is particularly relevant when index level assignments are made inside a loop.
+Often the loop variable is used as the index for the value assignment, and in this case, it is usually already certain to be within the valid range for the targetted Vector instance.
+For example:
+
+```actionscript
+var l:uint = myVec.length;
+for (var i:uint = 0; i<l; i++) {
+ myVec[i] = i/SOME_CONST;
+ //in the above case i is always in the valid range for myVec
+}
+```
+
+In the above example, the compiler will by default be generating something in javascript that is (pseudocode) sort of like:
+`myVec[myVec.checkIndex(i)] = i/SOME_CONST;`
+
+Where `myVec.checkIndex(i)` in the pseudocode checks that `i` is in the valid range for myVec, and returns it unchanged if it is, otherwise throws an error that corresponds to what would happen at runtime in AVM.
+
+This is obviously not needed in the above case, and will definitely slow the loop down, so for performance reasons it is important to remove this generated code for large loops.
+So once everything has been verified to work correctly in your app, it is often a good idea to switch off the generation of this type of code.
+As with other settings it is possible to switch it off or on with more specificity by using [doc comment directives](create-an-application/optimizations/doc-comment-directives.html).
+If you are porting legacy as3 code, it can be useful to check that the code does not rely on error trapping for any of these cases before switching this setting off.
+
+***Pro tip:***
+How do I know how much of my code is being affected by this setting?
+In javascript the **js‑debug** output, you can do a ***search in files*** for the string **Language.CHECK_INDEX**
+* * *
+
diff --git a/create-an-application/optimizations/doc-comment-directives.md b/create-an-application/optimizations/doc-comment-directives.md
new file mode 100644
index 0000000..7f7eaf8
--- /dev/null
+++ b/create-an-application/optimizations/doc-comment-directives.md
@@ -0,0 +1,243 @@
+---
+# 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.
+
+layout: docpage
+title: Doc-Comment Directives
+---
+## (Optimization options)
+# Doc-Comment Directives
+
+
+Warning: This document is a work-in-progress/undergoing review.
+
+
+These settings are actionscript code level settings. They are implemented in the form of instructions to the compiler based on doc-comment tags, frequently as annotations against members of classes.
+They are always in the format
+ **@royale{name here}**
+
+They have no case variation (all lower case, not camel case, for example) and may have arguments that follow after some white space. They are fully expressed on a single line, and a newline terminates them.
+
+
+|[Suppress Warnings](create-an-application/optimizations/doc-comment-directives.html#suppress-warnings) |[@royalesuppresspublicvarwarning](create-an-application/optimizations/doc-comment-directives.html#royalesuppresspublicvarwarning) |
+|[Output Optimizations](create-an-application/optimizations/doc-comment-directives.html#output-optimizations) |[@royaleigorecoercion](create-an-application/optimizations/doc-comment-directives.html#royaleigorecoercion) |
+| |[@royalesuppressresolveuncertain](create-an-application/optimizations/doc-comment-directives.html#royalesuppressresolveuncertain) |
+| |[@royalesuppresscompleximplicitcoercion](create-an-application/optimizations/doc-comment-directives.html#royalesuppresscompleximplicitcoercion) |
+| |[@royalesuppressvectorindexcheck](create-an-application/optimizations/doc-comment-directives.html#royalesuppressvectorindexcheck) |
+|[Miscellaneous](create-an-application/optimizations/doc-comment-directives.html#miscellaneous) |[@royalesuppressexport](create-an-application/optimizations/doc-comment-directives.html#royalesuppressexport) |
+| |[@royalesuppressclosure](create-an-application/optimizations/doc-comment-directives.html#royalesuppressclosure) |
+
+
+* * *
+## Todo
+The following are placeholders/reminders for future content while this document is being worked on:
+>@royaleignoreimport
+>@royaledebug
+>@royalenoimplicitstringconversion
+
+* * *
+## Suppress Warnings
+
+### @royalesuppresspublicvarwarning {#royalesuppresspublicvarwarning}
+This is used to suppress warning output by the compiler.
+
+public variables are not protected from renaming optimizations by javascript in a way that permits them to continue to be accessible via dynamic access.
+This means that for:
+
+class MyThing{
+ public var myImportantVar:String = 'myValue';
+}
+```actionscript
+var myThing:MyThing = new MyThing();
+var s:String = myThing.myImportantVar; //this always works
+var fieldName:String = 'myImportantVar';
+s = myThing[fieldName]; //this will work in a js-debug build, but may not work in js-release
+```
+Because of issues like the above, the Royale compiler outputs a warning to alert the developer.
+However in many cases, the dynamic access may not be needed, and using a public var will be fine.
+To prevent the warning from the compiler, the doc comment directive can be used as follows:
+```actionscript
+/**
+* @royalesuppresspublicvarwarning
+*/
+public var myImportantVar:String = 'myValue';
+```
+* * *
+## Output Optimizations
+
+### @royaleigorecoercion type {#royaleigorecoercion}
+
+Used for: performance tuning, code size tuning.
+This is an option to avoid compiler output of coercions of a certain type.
+It can help avoid unnecessary code and improve performance.
+
+A simplistic, illustrative example is:
+```actionscript
+if (myVar is MyClass) { //this generates code to check if myVar is of type 'MyClass'
+ (myVar as MyClass).myClassMethod();
+ //the above normally generates similar code to check if myVar is of type 'MyClass'
+ //or a subclass of MyClass, and if it is not, treats it as null
+ MyClass(myVar).myOtherClassMethod();
+ //the above normally generates similar code to check if myVar is of type 'MyClass'
+ //or a subclass of MyClass, and if it is not, throws an error
+}
+```
+In both the above examples, the outer conditional `myVar is MyClass` check already assures us that myVar resolves to 'MyClass' as a type.
+So the extra overhead of code that performs `myVar as MyClass` or `MyClass(myVar)` coercions is redundant, because we can already be sure it will resolve successfully.
+If the definition of MyClass is in a package called mypackage, then its **fully qualified name** is mypackage.MyClass.
+The following can then be used to avoid the redundant (as described above) javascript output code:
+```
+/**
+* @royaleigorecoercion mypackage.MyClass
+* /
+```
+
+* * *
+
+### @royalesuppressresolveuncertain optional_arg {#royalesuppressresolveuncertain}
+
+Used for: performance tuning, code size tuning.
+This is a local variation for controlling specificity of the corresponding compiler configuration setting '-js-resolve-uncertain'.
+Please read the [Strict equality comparisons](create-an-application/optimizations/compiler-configuration-settings.html#strict-equality-comparisons) section of [Compiler Configuration Settings](create-an-application/optimizations/compiler-configuration-settings.html) for general information about this setting.
+
+
+How to use:
+A simplistic example is:
+```actionscript
+/**
+* setting goes here
+*/
+public function testResolveUncertain():void{
+ var myClass:Class = int;
+ if (new myClass(30) === 30) trace('it worked!);
+ var myOtherClass:Class = String;
+ if (new myOtherClass('test') === 'test') trace('it worked again!);
+}
+```
+In the above example, both of 'new myClass(30)' and 'new myOtherClass('test')' will have extra code to cover the cases where variations occur in javascript.
+
+**@royalesuppressresolveuncertain false**
+
+Using the above setting, if the compiler configuration setting is -js-resolve-uncertain=false, then the above annotation will override that locally to turn it on (true).
+This only affects the code scope of the annnotated method definition.
+
+**@royalesuppressresolveuncertain true**
+or simply:
+**@royalesuppressresolveuncertain**
+Both of the above settings will be the same as '-js-resolve-uncertain=false' for the annotated method's code scope.
+
+**@royalesuppressresolveuncertain myClass**
+Using the above setting, if the compiler configuration setting is -js-resolve-uncertain=true, then the above annotation will override that locally to turn it off (false) only for the myClass Class variable and not for the myOtherClass Class variable.
+
+
+* * *
+
+### @royalesuppressvectorindexcheck optional_arg {#royalesuppressvectorindexcheck}
+
+Used for: performance tuning, code size tuning.
+This is a local variation for controlling specificity of the corresponding configuration setting '-js-vector-index-checks'.
+
+Please read the [Vector Index Checking](create-an-application/optimizations/compiler-configuration-settings.html#vector-index-checking) section of [Compiler Configuration Settings](create-an-application/optimizations/compiler-configuration-settings.html) for general information about this setting.
+
+How to use:
+A simplistic example is:
+```actionscript
+/**
+* setting goes here
+*/
+public function myTest():void{
+ var vi:Vector.<int> = new <int>[0, 1, 2, 3, 4];
+ vi[8] = 0;
+ //index 8 above is too high
+ //by default this will throw a RangeError, but if
+ //@royalesuppressvectorindexcheck is used to suppress index checking,
+ //no runtime error would be thrown in javascript.
+}
+```
+
+**@royalesuppressvectorindexcheck false**
+
+In the above case, if the compiler configuration setting is *-js-vector-index-checks=false*, then the above annotation will override that locally to turn it on (true).
+This only affects the code scope of the annnotated method definition.
+
+**@royalesuppressvectorindexcheck true**
+or simply:
+**@royalesuppressvectorindexcheck**
+
+Both of the above settings will be the same as '-js-vector-index-checks=false' for the annotated method's code scope.
+
+**@royalesuppressvectorindexcheck vi**
+
+In the above case, the effect is as if there was a '-js-vector-index-checks=false' setting applied specifically to any Vector with a variable name of 'vi'
+
+
+* * *
+
+### @royalesuppresscompleximplicitcoercion optional_arg {#royalesuppresscompleximplicitcoercion}
+
+Used for: performance tuning, code size tuning.
+This is a local variation for controlling specificity of the corresponding configuration setting '-js-complex-implicit-coercions'.
+Please read the [Implict Coercions of non-primitive types](create-an-application/optimizations/compiler-configuration-settings.html#implicit-complex-coercions) section in [Compiler Configuration Settings](create-an-application/optimizations/compiler-configuration-settings.html) for general information about this setting if you have not already done so.
+How to use:
+
+A simplistic example is:
+```actionscript
+/**
+* setting goes here
+*/
+public function testComplexImplicitCoercion():void{
+ var something:* = new Cat();
+ var myDog:Dog = something;
+}
+```
+In the above example, the default output will have extra code generated in javascript, that would be similar in actionscript to:
+`var myDog:Dog = Dog(something);`
+
+**@royalesuppresscompleximplicitcoercion false**
+
+Using the above setting, if the compiler configuration setting is -js-complex-implicit-coercions=false, then the above annotation will override that locally to turn it on (true).
+This only affects the code scope of the annnotated method definition.
+
+**@royalesuppresscompleximplicitcoercion true**
+or simply:
+**@royalesuppresscompleximplicitcoercion**
+Both of the above settings will be the same as '-js-complex-implicit-coercions=false' for the annotated method's code scope.
+
+**@royalesuppresscompleximplicitcoercion Dog**
+Note that in this example, Dog is a top level class (top level package). Otherwise it needs the fully qualified class name.
+Using the above setting, if the compiler configuration setting is -js-complex-implicit-coercions=true, then the above annotation will override that locally to turn it off (false) only for the implicit coercions involving the Dog class.
+As another example, if the definition of Dog is in a package called myanimals, then its fully qualified name is myanimals.Dog, and it should be expressed as follows:
+**@royalesuppresscompleximplicitcoercion myanimals.Dog**
+
+
+
+* * *
+## Miscellaneous
+
+The following are intended mainly for use by framework developers, but are documented here for completeness. In most cases these are not recommended for use in applications.
+They may be helpful in specific cases *when used with caution* for library development.
+
+### @royalesuppressexport {#royalesuppressexport}
+The above is used to prevent a public class member from having an exported setting in the release build.
+This can be used with classes that are used to emulate certain as3 language features in javascript, and often are intended only for output generated by the compiler and not used directly by a developer.
+It has the effect to making the annotated class member 'pay as you go' because if the compiler does not generate output that uses it, the code and any dependencies that are specific to it are eliminated from the release build output.
+They can also be used as another way to offer opt-in features, for a type of PAYG approach that works in regular actionscrip, and which could also be then supported in code via a bead for use in mxml.
+An example of this is the ExtraData class in the Reflection library, which has static methods to add opt-in support for additional reflection data.
+
+### @royalesuppressclosure {#royalesuppressclosure}
+The above is used to suppress closure generation inside a method scope of a class member.
+This breaks normal as3 behavior in the javascript output, and is only rarely needed in cases where there is an advantage to use it to generate javascript that treats the ***this*** reference differently in the generated code.
+An example of its usage is in the default Vector emulation code for javascript.
+Recommendation: use with caution and test extensively.
\ No newline at end of file