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 <[email protected]>
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
