Clarify instructions and add examples

readme.md

@@ -1,71 +1,107 @@
-
 Mirrors:
 ========
 
-The native mirror macro, permit to call native methods (JNI/CPP) from the haxe side easily.
-
-The metas:
-----
-
-Each meta support 2 arguments: the package / lib name, and the method name
-
-Both are optionals for JNI (it uses the haxe package & class name / method name by default)
-Both are needed for iOS & CPP.
+Mirror macros make it easy to call native methods (Java/C++) from Haxe. To enable them, add this before your class declaration:
 
-After the version 1.0.1 conditional compilation is no more needed, the call check itself if the Context defined the required flags (ios for iOS ...)
+```haxe
+@:build(ShortCuts.mirrors())
+```
 
 JNI calls:
-----
-
-It support both type of methods : static or non-static.
+----------
 
-In case of a static method it's easy:
+To call a static Java method, simply add `@JNI` before the Haxe function declaration:
 
 ```haxe
 @JNI
-function toto(arg1:String, arg2:Int, arg3:String):Bool{}
+public static function myStaticMethod(arg0:String, arg1:Int, arg2:String):Bool;
 ```
 
-In the case of a non-static method, you have to set as first argument of the method a dynamic value which is the java instance of the class (than you can by example get by calling a static java singleton method)
+Instance methods are more complicated. In Haxe, you would call `instance.myInstanceMethod()`, but to make a JNI instance method work, you have to call `myInstanceMethod(instance)`:
 
 ```haxe
 @JNI
-function toto(instance:Dynamic, arg2:Int , arg2:String):Bool{}
+public static function myInstanceMethod(instance:Dynamic, arg0:String, arg1:Int, arg2:String):Bool;
 ```
 
-The JNI signature of the method is automatically created.
+The macros are called "mirror macros" because they look for a Java function that exactly matches the Haxe function. If this is the class in Haxe...
+
+```haxe
+package com.example.mypackage;
+
+@:build(ShortCuts.mirrors())
+class MyClass {
+    @JNI
+    public static function myStaticMethod(arg0:String, arg1:Int, arg2:String):Bool;
+}
+```
 
-And the JNI method is called at the same time you call the method on the haxe side.
+The macro will look for a Java function in `com/example/mypackage/MyClass.java`, with exactly the same name, exactly the same arguments, and exactly the same return value. If you don't like this behavior, you can specify a custom package, class name, or method name.
 
-Like said earlier you can add additional arguments to the @JNI tag:
+To call a method with a different name:
+```haxe
+@JNI("javaMethodName")
+public static function haxeMethodName(arg0:String, arg1:Int, arg2:String):Bool;
+```
 
-To call a method named differently:
+To call a method from another class:
 ```haxe
-@JNI("methodJava")
-function toto(instance:Dynamic, arg2:Int , arg2:String):Bool{}
+@JNI("com.example.otherpackage.OtherClass", "javaMethodName")
+public static function haxeMethodName(arg0:String, arg1:Int, arg2:String):Bool;
 ```
 
-To class a method from another class:
+To set a different class as the default:
 ```haxe
-@JNI("another.class.java.Class","methodJava")
-function toto(instance:Dynamic, arg2:Int , arg2:String):Bool{}
+@:build(ShortCuts.mirrors())
+@JNI_DEFAULT_PACKAGE("com.example.otherpackage")
+@JNI_DEFAULT_CLASS_NAME("OtherClass")
+class MyClass {
+    @JNI
+    public static function haxeMethodName(arg0:String, arg1:Int, arg2:String):Bool;
+}
 ```
 
 CPP & iOS calls:
-----
+----------------
+
+The `@CPP` and `@IOS` tags take two arguments.
+
+The first argument is the name of the library to load from. For instance, if you include a library using `<ndll name="my-cpp-library" />`, then the first argument should be `"my-cpp-library"`. If you don't want to type this for every single method, you can specify a default library using the `@CPP_DEFAULT_LIBRARY` tag:
 
-They both behave the same way.
+```haxe
+@:build(ShortCuts.mirrors())
+@CPP_DEFAULT_LIBRARY("my-cpp-library")
+class MyClass {
+    @CPP
+    public static function myStaticMethod(arg0:String, arg1:Int, arg2:String):Bool;
+}
+```
+
+The second argument is the name of the primitive, as defined by `DEFINE_PRIM()` in C++. For OpenFL native extensions, `DEFINE_PRIM()` is located in ExternalInterface.cpp. You may omit the second argument if the Haxe method name matches the C++ method name.
 
-The first argument is the name of library (in the case of a OpenFL native extension if the ".a" filename)
+```haxe
+@CPP("my-cpp-library", "cppMethodName")
+public static function haxeMethodName(arg1:String, arg2:Int, arg3:String):Bool;
+```
 
-The second argument is the name of the primitive (in the case of a Open native extension, the primitive is defined into the ExternalInterface.cpp class)
+Finally, if the C++ methods all have the same prefix, you'll want to use the `@CPP_PRIMITIVE_PREFIX` tag:
 
 ```haxe
-@CPP("lib-name-of-extension","primitive_name")
-function toto(arg1:String, arg2:Int, arg3:String):Bool{}
+@:build(ShortCuts.mirrors())
+@CPP_DEFAULT_LIBRARY("my-cpp-library") @CPP_PRIMITIVE_PREFIX("prefix")
+class MyClass {
+    @CPP
+    public static function myMethod(arg0:String, arg1:Int, arg2:String):Bool;
+    @CPP
+    public static function yourMethod():Void;
+    @CPP
+    public static function someOtherMethod(arg0:Int, arg1:Bool):Void;
+}
 ```
 
-Developed by :
+This will add "`prefix_`" in front of the primitive names, resulting in `prefix_myMethod`, `prefix_yourMethod`, and `prefix_someOtherMethod`.
+
+Developed by:
 ----
 [Johann Martinache](https://github.com/shoebox) 
 [@shoe_box](https://twitter.com/shoe_box)

src/mirror/CppFieldTool.hx

@@ -68,7 +68,7 @@ class CppFieldTool
 		if ((entry.params == null || entry.params.length == 0) 
 			&& !meta.has(TagDefaultLibrary))
 		{
-			Context.error("Not default C++ library defined globary or locally", 
+			Context.error("Not default C++ library defined globally or locally", 
 				field.pos);
 		}