add documentation to `haxe.macro.Compiler.addGlobalMetadata` (closes #3721)

std/haxe/macro/Compiler.hx

@@ -266,6 +266,9 @@ class Compiler {
 		including the containing module has to be used
 		(e.g. msignal.Signal.Signal0).
 
+		This operation has no effect if the type has already been loaded, e.g.
+		through `Context.getType`.
+
 		@param path A package, module or sub-type dot path to keep.
 		@param paths An Array of package, module or sub-type dot paths to keep.
 		@param recursive If true, recurses into sub-packages for package paths.
@@ -280,6 +283,20 @@ class Compiler {
 		}
 	}
 
+	/**
+		Adds metadata `meta` to all types (if `toTypes = true`) or fields (if
+		`toFields = true`) whose dot-path matches `pathFilter`.
+
+		If `recursive` is true a dot-path is considered matched if it starts
+		with `pathFilter`. This automatically applies to path filters of
+		packages. Otherwise an exact match is required.
+
+		If `pathFilter` is the empty String `""` it matches everything (if
+		`recursive = true`) or only top-level types (if `recursive = false`).
+
+		This operation has no effect if the type has already been loaded, e.g.
+		through `Context.getType`.
+	**/
 	public static function addGlobalMetadata(pathFilter:String, meta:String, ?recursive:Bool = true, ?toTypes:Bool = true, ?toFields:Bool = false) {
 		untyped load("add_global_metadata",5)(untyped pathFilter.__s, meta.__s, recursive, toTypes, toFields);
 	}

typeload.ml

@@ -1494,14 +1494,16 @@ let check_global_metadata ctx f_add mpath tpath so =
 			(* always recurse into types of package paths *)
 			| (s1 :: s11 :: _),[s2] when is_lower_ident s2 && not (is_lower_ident s11)->
 				s1 = s2
-			| _,[] ->
+			| [_],[""] ->
+				true
+			| _,([] | [""]) ->
 				recursive
 			| [],_ ->
 				false
 			| (s1 :: sl1),(s2 :: sl2) ->
 				s1 = s2 && loop sl1 sl2
 		in
-		let add = ((field_mode && to_fields) || (not field_mode && to_types)) && (sl2 = [""] || loop sl1 sl2) in
+		let add = ((field_mode && to_fields) || (not field_mode && to_types)) && (loop sl1 sl2) in
 		if add then f_add m
 	) ctx.g.global_metadata