[java/cs] Added metadata documentation

[all] Added "Internal" meta flag to annotate metadatas that should only be used internally
Fixed issue #1239

ast.ml

@@ -30,12 +30,10 @@ module Meta = struct
 	type strict_meta =
 		| Abstract
 		| Access
-		| Alias
 		| Allow
 		| Annotation
 		| ArrayAccess
 		| AutoBuild
-		| BaseInterface
 		| Bind
 		| Bitmap
 		| Build
@@ -120,13 +118,11 @@ module Meta = struct
 		| Sound
 		| Struct
 		| SuppressWarnings
-		| Synchronized
 		| Throws
 		| To
 		| ToString
 		| Transient
 		| ValueUsed
-		| VarArgs
 		| Volatile
 		| UnifyMinDynamic
 		| Unreflective

common.ml

@@ -282,22 +282,21 @@ module MetaInfo = struct
 		| Platforms of platform list
 		| UsedOn of meta_usage
 		| UsedOnEither of meta_usage list
+    | Internal
 
 	let to_string = function
-		| Abstract -> ":abstract",("",[Platforms [Java;Cs]])
+		| Abstract -> ":abstract",("Sets the underlying class implementation as 'abstract'",[Platforms [Java;Cs]])
 		| Access -> ":access",("Forces private access to package, type or field",[HasParam "Target path";UsedOnEither [TClass;TClassField]])
-		| Alias -> ":alias",("",[Platforms [Java;Cs]])
 		| Allow -> ":allow",("Allows private access from package, type or field",[HasParam "Target path";UsedOnEither [TClass;TClassField]])
-		| Annotation -> ":annotation",("",[Platforms [Java;Cs]])
+    | Annotation -> ":annotation",("Annotation (@interface) definitions on -java-lib imports will be annotated with this metadata. Has no effect on types compiled by Haxe",[Platform Java; UsedOn TClass])
 		| ArrayAccess -> ":arrayAccess",("Allows [] access on an abstract",[UsedOnEither [TAbstract;TAbstractField]])
 		| AutoBuild -> ":autoBuild",("Extends @:build metadata to all extending and implementing classes",[HasParam "Build macro call";UsedOn TClass])
-		| BaseInterface -> ":baseInterface",("",[Platforms [Java;Cs]])
 		| Bind -> ":bind",("Override Swf class declaration",[Platform Flash;UsedOn TClass])
 		| Bitmap -> ":bitmap",("Embeds given bitmap data into the class (must extend flash.display.BitmapData)",[HasParam "Bitmap file path";UsedOn TClass;Platform Flash])
 		| Build -> ":build",("Builds a class or enum from a macro",[HasParam "Build macro call";UsedOnEither [TClass;TEnum]])
 		| BuildXml -> ":buildXml",("",[Platform Cpp])
-		| Class -> ":class",("",[Platforms [Java;Cs]])
-		| ClassCode -> ":classCode",("",[Platforms [Java;Cs]])
+    | Class -> ":class",("Used internally to annotate an enum that will be generated as a class",[Platforms [Java;Cs]; UsedOn TEnum; Internal])
+    | ClassCode -> ":classCode",("Used to inject platform-native code into a class",[Platforms [Java;Cs]; UsedOn TClass])
 		| Commutative -> ":commutative",("Declares an abstract operator as commutative",[UsedOn TAbstractField])
 		| CompilerGenerated -> ":compilerGenerated",("Marks a field as generated by the compiler. Shouldn't be used by the end user",[Platforms [Java;Cs]])
 		| CoreApi -> ":coreApi",("Identifies this class as a core api class (forces Api check)",[UsedOnEither [TClass;TEnum;TTypedef;TAbstract]])
@@ -308,10 +307,10 @@ module MetaInfo = struct
 		| Decl -> ":decl",("",[Platform Cpp])
 		| DefParam -> ":defParam",("?",[])
 		| Depend -> ":depend",("",[Platform Cpp])
-		| Deprecated -> ":deprecated",("",[Platforms [Java;Cs]])
-		| DynamicObject -> ":dynamicObject",("",[Platforms [Java;Cs]])
-		| Enum -> ":enum",("Used internally to annotate a class that was generated from an enum",[Platforms [Java;Cs]; UsedOn TClass])
-		| EnumConstructorParam -> ":enumConstructorParam",("Used internally to annotate GADT type parameters",[UsedOn TClass])
+    | Deprecated -> ":deprecated",("Automatically added by -java-lib on class fields annotated with @Deprecated annotation. Has no effect on types compiled by Haxe.",[Platform Java; UsedOnEither [TClass;TEnum;TClassField]])
+    | DynamicObject -> ":dynamicObject",("Used internally to identify the Dynamic Object implementation",[Platforms [Java;Cs]; UsedOn TClass; Internal])
+    | Enum -> ":enum",("Used internally to annotate a class that was generated from an enum",[Platforms [Java;Cs]; UsedOn TClass; Internal])
+    | EnumConstructorParam -> ":enumConstructorParam",("Used internally to annotate GADT type parameters",[UsedOn TClass; Internal])
 		| Expose -> ":expose",("Makes the class available on the window object",[HasParam "?Name=Class path";UsedOn TClass;Platform Js])
 		| Extern -> ":extern",("Marks the field as extern so it is not generated",[UsedOn TClassField])
 		| FakeEnum -> ":fakeEnum",("Treat enum as collection of values of the specified type",[HasParam "Type name";UsedOn TEnum])
@@ -324,28 +323,28 @@ module MetaInfo = struct
 		| Generic -> ":generic",("Marks a class or class field as generic so each type parameter combination generates its own type/field",[UsedOnEither [TClass;TClassField]])
 		| Getter -> ":getter",("Generates a native getter function on the given field",[HasParam "Class field name";UsedOn TClassField;Platform Flash])
 		| Hack -> ":hack",("Allows extending classes marked as @:final",[UsedOn TClass])
-		| HaxeGeneric -> ":haxeGeneric",("",[Platforms [Java;Cs]])
+    | HaxeGeneric -> ":haxeGeneric",("Used internally to annotate non-native generic classes",[Platform Cs; UsedOnEither[TClass;TEnum]; Internal])
 		| HeaderClassCode -> ":headerClassCode",("",[Platform Cpp])
 		| HeaderCode -> ":headerCode",("",[Platform Cpp])
 		| HeaderNamespaceCode -> ":headerNamespaceCode",("",[Platform Cpp])
 		| HxGen -> ":hxGen",("Annotates that an extern class was generated by Haxe",[Platforms [Java;Cs]; UsedOnEither [TClass;TEnum]])
 		| IfFeature -> ":ifFeature",("Causes a field to be kept by DCE if the given feature is part of the compilation",[HasParam "Feature name";UsedOn TClassField])
-		| Impl -> ":impl",("Used internally to mark abstract implementation fields",[UsedOn TAbstractField])
+    | Impl -> ":impl",("Used internally to mark abstract implementation fields",[UsedOn TAbstractField; Internal])
 		| Include -> ":include",("",[Platform Cpp])
 		| InitPackage -> ":initPackage",("?",[])
-		| Internal -> ":internal",("Generates the annotated field/class with 'internal' access",[Platforms [Java;Cs]; UsedOnEither[TClass;TEnum;TClassField]])
+		| Meta.Internal -> ":internal",("Generates the annotated field/class with 'internal' access",[Platforms [Java;Cs]; UsedOnEither[TClass;TEnum;TClassField]])
 		| IsVar -> ":isVar",("Forces a physical field to be generated for properties that otherwise would not require one",[UsedOn TClassField])
-		| JavaNative -> ":javaNative",("",[Platforms [Java;Cs]])
+    | JavaNative -> ":javaNative",("Automatically added by -java-lib on classes generated from JAR/class files",[Platform Java; UsedOnEither[TClass;TEnum]; Internal])
 		| Keep -> ":keep",("Causes a field or type to be kept by DCE",[])
 		| KeepInit -> ":keepInit",("Causes a class to be kept by DCE even if all its field are removed",[UsedOn TClass])
 		| KeepSub -> ":keepSub",("Extends @:keep metadata to all implementing and extending classes",[UsedOn TClass])
 		| Meta -> ":meta",("Internally used to mark a class field as being the metadata field",[])
 		| Macro -> ":macro",("(deprecated)",[])
-		| MaybeUsed -> ":maybeUsed",("Internally used by DCE to mark fields that might be kept",[])
+    | MaybeUsed -> ":maybeUsed",("Internally used by DCE to mark fields that might be kept",[Internal])
 		| MultiType -> ":multiType",("Specifies that an abstract chooses its this-type from its @:to functions",[UsedOn TAbstract])
 		| Native -> ":native",("Rewrites the path of a class or enum during generation",[HasParam "Output type path";UsedOnEither [TClass;TEnum]])
-		| NativeGen -> ":nativeGen",("",[Platforms [Java;Cs]])
-		| NativeGeneric -> ":nativeGeneric",("",[Platforms [Java;Cs]])
+    | NativeGen -> ":nativeGen",("Annotates that a type should be treated as if it were an extern definition - platform native",[Platforms [Java;Cs]; UsedOnEither[TClass;TEnum]])
+    | NativeGeneric -> ":nativeGeneric",("Used internally to annotate native generic classes",[Platform Cs; UsedOnEither[TClass;TEnum]; Internal])
 		| NoCompletion -> ":noCompletion",("Prevents the compiler from suggesting completion on this field",[UsedOn TClassField])
 		| NoDebug -> ":noDebug",("Does not generate debug information into the Swf even if -debug is set",[UsedOnEither [TClass;TClassField];Platform Flash])
 		| NoDoc -> ":noDoc",("Prevents a type from being included in documentation generation",[])
@@ -360,35 +359,33 @@ module MetaInfo = struct
 		| Overload -> ":overload",("Allows the field to be called with different argument types",[HasParam "Function specification (no expression)";UsedOn TClassField])
 		| Public -> ":public",("Marks a class field as being public",[UsedOn TClassField])
 		| PublicFields -> ":publicFields",("Forces all class fields of inheriting classes to be public",[UsedOn TClass])
-		| PrivateAccess -> ":privateAccess",("Internally used by the typer to allow context-sensitive private access",[])
+    | PrivateAccess -> ":privateAccess",("Internally used by the typer to allow context-sensitive private access",[Internal])
 		| Protected -> ":protected",("Marks a class field as being protected",[UsedOn TClassField])
-		| ReadOnly -> ":readOnly",("",[Platforms [Java;Cs]])
-		| RealPath -> ":realPath",("Internally used on @:native types to retain original path information",[])
+    | ReadOnly -> ":readOnly",("Generates a field with the 'readonly' native keyword",[Platform Cs; UsedOn TClassField])
+    | RealPath -> ":realPath",("Internally used on @:native types to retain original path information",[Internal])
 		| Remove -> ":remove",("Causes an interface to be removed from all implementing classes before generation",[UsedOn TClass])
 		| Require -> ":require",("Allows access to a field only if the specified compiler flag is set",[HasParam "Compiler flag to check";UsedOn TClassField])
-		| ReplaceReflection -> ":replaceReflection",("",[Platforms [Java;Cs]])
+    | ReplaceReflection -> ":replaceReflection",("Used internally to specify a function that should replace its internal __hx_functionName counterpart",[Platforms [Java;Cs]; UsedOnEither[TClass;TEnum]; Internal])
 		| Rtti -> ":rtti",("Adds runtime type informations",[UsedOn TClass])
 		| Runtime -> ":runtime",("?",[])
 		| RuntimeValue -> ":runtimeValue",("Marks an abstract as being a runtime value",[UsedOn TAbstract])
 		| Setter -> ":setter",("Generates a native getter function on the given field",[HasParam "Class field name";UsedOn TClassField;Platform Flash])
-		| SkipCtor -> ":skipCtor",("",[Platforms [Java;Cs]])
-		| SkipReflection -> ":skipReflection",("",[Platforms [Java;Cs]])
+    | SkipCtor -> ":skipCtor",("Used internally to generate a constructor as if it were a native type (no __hx_ctor)",[Platforms [Java;Cs]; Internal])
+    | SkipReflection -> ":skipReflection",("Used internally to annotate a field that shouldn't have its reflection data generated",[Platforms [Java;Cs]; UsedOn TClassField; Internal])
 		| Sound -> ":sound",( "Includes a given .wav or .mp3 file into the target Swf and associates it with the class (must extend flash.media.Sound)",[HasParam "File path";UsedOn TClass;Platform Flash])
-		| Struct -> ":struct",("",[Platforms [Java;Cs]])
-		| SuppressWarnings -> ":suppressWarnings",("",[Platforms [Java;Cs]])
-		| Synchronized -> ":synchronized",("",[Platforms [Java;Cs]])
-		| Throws -> ":throws",("",[Platforms [Java;Cs]])
+    | Struct -> ":struct",("Marks a class definition as a struct.",[Platform Cs; UsedOn TClass])
+    | SuppressWarnings -> ":suppressWarnings",("Adds a SuppressWarnings annotation for the generated Java class",[Platform Java; UsedOn TClass])
+    | Throws -> ":throws",("Adds a 'throws' declaration to the generated function.",[HasParam "Type as String"; Platform Java; UsedOn TClassField])
 		| To -> ":to",("Specifies that the field of the abstract is a cast operation to the type identified in the function",[UsedOn TAbstractField])
-		| ToString -> ":toString",("Internally used",[])
-		| Transient -> ":transient",("",[Platforms [Java;Cs]])
-		| ValueUsed -> ":valueUsed",("Internally used by DCE to mark an abstract value as used",[])
-		| VarArgs -> ":varArgs",("",[Platforms [Java;Cs]])
+    | ToString -> ":toString",("Internally used",[Internal])
+    | Transient -> ":transient",("Adds the 'transient' flag to the class field",[Platform Java; UsedOn TClassField])
+    | ValueUsed -> ":valueUsed",("Internally used by DCE to mark an abstract value as used",[Internal])
 		| Volatile -> ":volatile",("",[Platforms [Java;Cs]])
 		| UnifyMinDynamic -> ":unifyMinDynamic",("Allows a collection of types to unify to Dynamic",[UsedOn TClassField])
 		| Unreflective -> ":unreflective",("",[Platform Cpp])
-		| Unsafe -> ":unsafe",("",[Platforms [Java;Cs]])
+    | Unsafe -> ":unsafe",("Declares a class, or a method with the C#'s 'unsafe' flag",[Platform Cs; UsedOnEither [TClass;TClassField]])
 		| Usage -> ":usage",("?",[])
-		| Used -> ":used",("Internally used by DCE to mark a class or field as used",[])
+    | Used -> ":used",("Internally used by DCE to mark a class or field as used",[Internal])
 		| Last -> assert false
 		(* do not put any custom metadata after Last *)
 		| Dollar s -> "$" ^ s,("",[])

gencommon.ml

@@ -8197,7 +8197,7 @@ struct
     let priority = min_dep +. 10.
 
     let default_implementation gen baseclass baseinterface basedynamic =
-      baseinterface.cl_meta <- (Meta.BaseInterface, [], baseinterface.cl_pos) :: baseinterface.cl_meta;
+      (* baseinterface.cl_meta <- (Meta.BaseInterface, [], baseinterface.cl_pos) :: baseinterface.cl_meta; *)
       let rec run md =
         (if is_hxgen md then
           match md with
@@ -8231,10 +8231,10 @@ struct
   *)
   let priority = solve_deps name [DAfter UniversalBaseClass.priority]
 
-  let configure ?slow_invoke ctx =
+  let configure ?slow_invoke ctx baseinterface =
     let gen = ctx.rcf_gen in
     let run = (fun md -> match md with
-      | TClassDecl cl when is_hxgen md && ( not cl.cl_interface || Meta.has Meta.BaseInterface cl.cl_meta ) ->
+      | TClassDecl cl when is_hxgen md && ( not cl.cl_interface || cl.cl_path = baseinterface.cl_path ) ->
         (if Meta.has Meta.ReplaceReflection cl.cl_meta then replace_reflection ctx cl);
         (implement_dynamics ctx cl);
         (if not (PMap.mem (gen.gmk_internal_name "hx" "lookupField") cl.cl_fields) then implement_final_lookup ctx cl);
@@ -8448,7 +8448,6 @@ struct
             cf
         in
         cl.cl_statics <- PMap.add cf.cf_name cf cl.cl_statics;
-        cf.cf_meta <- (Meta.Alias, [ EConst( String (string_of_int old_i) ), pos ], pos) :: [];
         cf
       ) en.e_names in
       let constructs_cf = mk_class_field "constructs" (basic.tarray basic.tstring) true pos (Var { v_read = AccNormal; v_write = AccNormal }) [] in

gencs.ml

@@ -2013,7 +2013,7 @@ let configure gen =
     eexpr = TCall(slow_invoke, [ethis; efield; eargs]);
     etype = t_dynamic;
     epos = ethis.epos;
-  } );
+  } ) object_iface;
 
   let objdecl_fn = ReflectionCFs.implement_dynamic_object_ctor rcf_ctx dynamic_object in
 

genjava.ml

@@ -1871,7 +1871,7 @@ let configure gen =
     eexpr = TCall(slow_invoke, [ethis; efield; eargs]);
     etype = t_dynamic;
     epos = ethis.epos;
-  } );
+  } ) object_iface;
 
   let objdecl_fn = ReflectionCFs.implement_dynamic_object_ctor rcf_ctx dynamic_object in
 
@@ -2418,10 +2418,10 @@ let convert_java_enum ctx p pe =
           readonly := true;
           jf_constant := None;
         | _ -> jf_constant := None)
-      | JSynchronized -> cff_meta := (Meta.Synchronized, [], p) :: !cff_meta
+      (* | JSynchronized -> cff_meta := (Meta.Synchronized, [], p) :: !cff_meta *)
       | JVolatile -> cff_meta := (Meta.Volatile, [], p) :: !cff_meta
       | JTransient -> cff_meta := (Meta.Transient, [], p) :: !cff_meta
-      | JVarArgs -> cff_meta := (Meta.VarArgs, [], p) :: !cff_meta
+      (* | JVarArgs -> cff_meta := (Meta.VarArgs, [], p) :: !cff_meta *)
       | _ -> ()
     ) field.jf_flags;
 

main.ml

@@ -1056,25 +1056,28 @@ try
 				let d = Obj.magic i in
 				if d <> Meta.Last then begin
 					let t, (doc,flags) = MetaInfo.to_string d in
-					let params = ref [] and used = ref [] and pfs = ref [] in
-					List.iter (function
-						| MetaInfo.HasParam s -> params := s :: !params
-						| MetaInfo.Platform f -> pfs := f :: !pfs
-						| MetaInfo.Platforms fl -> pfs := fl @ !pfs
-						| MetaInfo.UsedOn u -> used := u :: !used
-						| MetaInfo.UsedOnEither ul -> used := ul @ !used
-					) flags;
-					let params = (match List.rev !params with
-						| [] -> ""
-						| l -> "(" ^ String.concat "," l ^ ")"
-					) in
-					let pfs = (match List.rev !pfs with
-						| [] -> ""
-						| [p] -> " (" ^ platform_name p ^ " only)"
-						| pl -> " (for " ^ String.concat "," (List.map platform_name pl) ^ ")"
-					) in
-					let str = "@" ^ t ^ params ^ " : " ^ doc ^ pfs in
-					str :: loop (i + 1)
+					if not (List.mem MetaInfo.Internal flags) then begin
+						let params = ref [] and used = ref [] and pfs = ref [] in
+						List.iter (function
+							| MetaInfo.HasParam s -> params := s :: !params
+							| MetaInfo.Platform f -> pfs := f :: !pfs
+							| MetaInfo.Platforms fl -> pfs := fl @ !pfs
+							| MetaInfo.UsedOn u -> used := u :: !used
+							| MetaInfo.UsedOnEither ul -> used := ul @ !used
+						) flags;
+						let params = (match List.rev !params with
+							| [] -> ""
+							| l -> "(" ^ String.concat "," l ^ ")"
+						) in
+						let pfs = (match List.rev !pfs with
+							| [] -> ""
+							| [p] -> " (" ^ platform_name p ^ " only)"
+							| pl -> " (for " ^ String.concat "," (List.map platform_name pl) ^ ")"
+						) in
+						let str = "@" ^ t ^ params ^ " : " ^ doc ^ pfs in
+						str :: loop (i + 1)
+					end else
+						loop (i + 1)
 				end else
 					[]
 			in