This is an automated email from the ASF dual-hosted git repository.
joshtynjala pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/royale-docs.git
commit e1cd406023ceecaffba474170ca513e571a5b35a
Author: Josh Tynjala <joshtynj...@apache.org>
AuthorDate: Wed Jun 11 10:01:09 2025 -0700
code formatting and syntax coloring tweaks
---
.../optimizations/doc-comment-directives.md | 45 ++++++++++++++--------
features/as3/classes-and-functions.md | 15 ++++----
features/as3/interfaces.md | 8 ++--
features/as3/packages.md | 5 ++-
libraries/compiled-code-libraries.md | 5 +--
libraries/crux/quickstart.md | 2 +-
6 files changed, 49 insertions(+), 31 deletions(-)
diff --git a/create-an-application/optimizations/doc-comment-directives.md
b/create-an-application/optimizations/doc-comment-directives.md
index 9537e1f..3e275b5 100644
--- a/create-an-application/optimizations/doc-comment-directives.md
+++ b/create-an-application/optimizations/doc-comment-directives.md
@@ -59,25 +59,32 @@ 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{
+```as3
+class MyThing {
public var myImportantVar:String = 'myValue';
}
+```
+
```as3
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:
+
```as3
/**
-* @royalesuppresspublicvarwarning
-*/
+ * @royalesuppresspublicvarwarning
+ */
public var myImportantVar:String = 'myValue';
```
+
* * *
+
## Output Optimizations
### @royaleigorecoercion type {#royaleigorecoercion}
@@ -89,6 +96,7 @@ The `as` keyword in ActionScript has two purposes. The first
is to tell the comp
If runtime coercion is not needed, the `@royaleigorecoercion` option can be
used. It can help avoid unnecessary code and improve performance.
A simplistic, illustrative example is:
+
```as3
if (myVar is MyClass) { //this generates code to check if myVar is of type
'MyClass'
(myVar as MyClass).myClassMethod();
@@ -99,14 +107,16 @@ if (myVar is MyClass) { //this generates code to check if
myVar is of type 'MyCl
//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:
-```
+
+```as3
/**
-* @royaleigorecoercion mypackage.MyClass
-* /
+ * @royaleigorecoercion mypackage.MyClass
+ */
```
* * *
@@ -124,17 +134,19 @@ Please read the [Strict equality
comparisons](create-an-application/optimization
How to use:
A simplistic example is:
+
```as3
/**
-* setting goes here
-*/
-public function testResolveUncertain():void{
+ * 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**
@@ -162,11 +174,12 @@ Please read the [Vector Index
Checking](create-an-application/optimizations/comp
How to use:
A simplistic example is:
+
```as3
/**
-* setting goes here
-*/
-public function myTest():void{
+ * 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
@@ -202,15 +215,17 @@ Please read the [Implict Coercions of non-primitive
types](create-an-application
How to use:
A simplistic example is:
+
```as3
/**
-* setting goes here
-*/
-public function testComplexImplicitCoercion():void{
+ * 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);`
diff --git a/features/as3/classes-and-functions.md
b/features/as3/classes-and-functions.md
index 4c3860c..beedf93 100644
--- a/features/as3/classes-and-functions.md
+++ b/features/as3/classes-and-functions.md
@@ -30,16 +30,16 @@ As mentioned in [packages](features/as3/packages), each
file in ActionScript nee
## Inheritance and interfaces
ActionScript classes can only inherit from a single `super` class, but you can
declare multiple interfaces. So if you need a class to be more than one
unrelated types, you should use [interfaces](features/as3/interfaces) to
declare your types rather than classes. Interfaces is very often a better
design choice that classes for types either way. Sub-classing and declaring
interfaces looks like this:
-```
+```as3
public class SubClass extends SuperClass implements IFoo, IBaz, IBar
```
## Constructors
Constructors in ActionScript are optional. If you need to initialize something
in your class you should always declare a constructor and you can define at
which point the `super` class is instantiated by calling `super()` inside the
constructor. Subclasses and super-classes do not need to have the same number
of arguments so the following is perfectly valid:
-```
-package{
- public class SubClass(){
+```as3
+package {
+ public class SubClass() {
foo = "foo";
super("baz")
}
@@ -68,9 +68,9 @@ In Royale, it's generally not recommended to use `this`
inside non-instance meth
## Package level functions
You don't need to declare a class to use code. You can have "utility"
functions as first class citizens. To create a public function you create a
file similar to a class (but name it camel-case). Assuming your file structure
is like so: `src/com/acme/doAwesome.as` Inside the file you declare the
function like this:
-```
-package com.acme{
- public function doAwesome(notSoAwesome:Object):Awesome{
+```as3
+package com.acme {
+ public function doAwesome(notSoAwesome:Object):Awesome {
return new Awesome(
doSomethingComplicatedInTheSamePackage(notSoAwesome)
);
@@ -82,6 +82,7 @@ Then `doAwesome()` is available anywhere in your project.
Your IDE should `impor
## Static classes and singletons
One of the cool new features in ActionScript is [private
constructors](features/as3/private-constructors). Use that if you have a class
that you want to use as static-only class or as a
[Singleton](https://en.wikipedia.org/wiki/Singleton_pattern)
+
## Instance, static and utility functions
The question is then when to use which.
- For OOP programming, you generally want to use instantiated classes.
diff --git a/features/as3/interfaces.md b/features/as3/interfaces.md
index 6267886..ea400b0 100644
--- a/features/as3/interfaces.md
+++ b/features/as3/interfaces.md
@@ -28,6 +28,7 @@ Interfaces in ActionScript 3
Interfaces is one of the core types in ActionScript. An interface is used to
define a type of an object independent of the implementation. While classes are
where you implement a type, interfaces are where you *declare* the type.
Classes must have function bodies, and interfaces *cannot* have function bodies.
Interfaces *do not* have to declare anything. You can declare an interface
type which does not require any implementation. This is useful if you want to
declare a group of classes belong to a specific type or groups of type. You can
even use use `myInstance is IFoo` at runtime to check types. This type check is
completely implementation independent.
+
## What can you declare in interfaces?
Interfaces do not define *scope*. You don't declare something public. Also,
interfaces are only for *methods*. You cannot declare variables in an
interface. You *can* (and should) declare getter and/or setters in interfaces,
but those must be implemented in your classes as getter and setter functions
and not vars.
@@ -38,9 +39,10 @@ Interfaces *must* be implemented as classes. You cannot
declare an interface for
## What does an interface look like?
Here's one example
-```
-package com.acme{
- public interface IFoo{
+
+```as3
+package com.acme {
+ public interface IFoo {
function get name():String;
function set name(name:String):void;
function sayFoo(output:IOutput):void;
diff --git a/features/as3/packages.md b/features/as3/packages.md
index dad6561..1a23dc9 100644
--- a/features/as3/packages.md
+++ b/features/as3/packages.md
@@ -26,7 +26,7 @@ Packages in ActionScript 3
Code in ActionScript is structured the same way Java code is structured. Each
ActionScript file must declare its package and wrap any externally visible
class in the package. A top level package does not need a name. So for a `Foo`
class at the top level, it would look like this:
-```
+```as3
package {
class Foo {
public function Foo() {
@@ -34,9 +34,10 @@ package {
}
}
```
+
You can name your folder structure any way you like, but an accepted
convention is to nest it in a unique domain to prevent potential package
conflicts. So for a class `MyFoo` you might have a folder structure like this:
`src/com/acme/MyFoo.as` and the class would look like this:
-```
+```as3
package com.acme {
class MyFoo {
public function MyFoo() {
diff --git a/libraries/compiled-code-libraries.md
b/libraries/compiled-code-libraries.md
index c75b3b9..7b5f12d 100644
--- a/libraries/compiled-code-libraries.md
+++ b/libraries/compiled-code-libraries.md
@@ -66,9 +66,8 @@ The namespace for your manifest is declared in
`compile-config.xml` and `js-comp
## The main class file
In order for classes to be included in your SWC, you need to actually use them
somewhere. Any classes which are declared in your manifest are considered
"used", and they along with all their dependencies will be included. However,
there will likely be other classes and utility functions which are not in the
manifest that you want to include. The simplest solution for this is to have a
Class which references all the classes you want included. To do this, you
include `MyLibrary.as` at the [...]
-```
+```actionscript
package {
-
internal class MyLibrary {
import com.example.ClassA;ClassA;
import com.example.ClassB;ClassB;
@@ -76,8 +75,8 @@ package {
import com.example.ClassD;ClassD;
}
}
-
```
+
Just referencing the classes like that is enough to have them included.
## The CSS file
diff --git a/libraries/crux/quickstart.md b/libraries/crux/quickstart.md
index 42cc537..26e145c 100644
--- a/libraries/crux/quickstart.md
+++ b/libraries/crux/quickstart.md
@@ -156,7 +156,7 @@ In addition to injecting a bean, you can inject individual
bean properties. In t
//example of setter style binding Injection
[Inject( source = "userController.currentUser", bind = "true" )]
- public function setUser(val:User):void{
+ public function setUser(val:User):void {
this.user = val;
}
]]>
