Improvements to --help-defines and --help-metas (#8350)

* add manual field to JSON schemas

* add manual references from current manual list

* show parameters in --help-defines, formatting

* mark meta and define parameters, add more manual references

* change manual field to links

* more reformatting

* [display] add manual links to metadata results

* fix manual field in schemata

* relevant

* fix CI

.vscode/schemas/define.schema.json

@@ -48,6 +48,15 @@
 			"devcomment": {
 				"type": "string",
 				"markdownDescription": "Internal comment that is not exposed."
+			},
+			"links": {
+				"type": "array",
+				"markdownDescription": "Relevant URLs.",
+				"minItems": 1,
+				"items": {
+					"type": "string",
+					"format": "uri"
+				}
 			}
 		},
 		"required": [

.vscode/schemas/meta.schema.json

@@ -70,6 +70,15 @@
 						"TAnyField"
 					]
 				}
+			},
+			"links": {
+				"type": "array",
+				"markdownDescription": "Relevant URLs.",
+				"minItems": 1,
+				"items": {
+					"type": "string",
+					"format": "uri"
+				}
 			}
 		},
 		"required": [

src-json/define.json

@@ -2,148 +2,154 @@
 	{
 		"name": "AbsolutePath",
 		"define": "absolute_path",
-		"doc": "Print absolute file path in trace output"
+		"doc": "Print absolute file path in trace output."
 	},
 	{
 		"name": "AdvancedTelemetry",
 		"define": "advanced-telemetry",
-		"doc": "Allow the SWF to be measured with Monocle tool",
+		"doc": "Allow the SWF to be measured with Monocle tool.",
 		"platforms": ["flash"]
 	},
 	{
 		"name": "AnnotateSource",
 		"define": "annotate_source",
-		"doc": "Add additional comments to generated source code",
+		"doc": "Add additional comments to generated source code.",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "As3",
 		"define": "as3",
-		"doc": "Defined when outputting flash9 as3 source code"
+		"doc": "Defined when outputting flash9 as3 source code."
 	},
 	{
 		"name": "CheckXmlProxy",
 		"define": "check_xml_proxy",
-		"doc": "Check the used fields of the xml proxy"
+		"doc": "Check the used fields of the XML proxy."
 	},
 	{
 		"name": "CoreApi",
 		"define": "core_api",
-		"doc": "Defined in the core api context"
+		"doc": "Defined in the core API context."
 	},
 	{
 		"name": "CoreApiSerialize",
 		"define": "core_api_serialize",
-		"doc": "Mark some generated core api classes with the Serializable attribute on C#",
+		"doc": "Mark some generated core API classes with the `Serializable` attribute on C#.",
 		"platforms": ["cs"]
 	},
 	{
 		"name": "Cppia",
 		"define": "cppia",
-		"doc": "Generate cpp instruction assembly"
+		"doc": "Generate cpp instruction assembly."
 	},
 	{
 		"name": "CsVer",
 		"define": "cs_ver",
-		"doc": "The C# version to target",
+		"doc": "The C# version to target.",
 		"platforms": ["cs"]
 	},
 	{
 		"name": "NoCppiaAst",
 		"define": "nocppiaast",
-		"doc": "Use legacy cppia generation"
+		"doc": "Use legacy cppia generation."
 	},
 	{
 		"name": "Dce",
 		"define": "dce",
-		"doc": "<mode:std|full|no> Set the dead code elimination mode (default std)"
+		"doc": "Set the dead code elimination mode. (default: std)",
+		"params": ["mode: std | full | no"],
+		"links": ["https://haxe.org/manual/cr-dce.html"]
 	},
 	{
 		"name": "DceDebug",
 		"define": "dce_debug",
-		"doc": "Show DCE log"
+		"doc": "Show DCE log.",
+		"links": ["https://haxe.org/manual/cr-dce.html"]
 	},
 	{
 		"name": "Debug",
 		"define": "debug",
-		"doc": "Activated when compiling with -debug"
+		"doc": "Activated when compiling with -debug."
 	},
 	{
 		"name": "DisableUnicodeStrings",
 		"define": "disable_unicode_strings",
-		"doc": "Disable unicode support in String type on some platforms",
+		"doc": "Disable Unicode support in `String` type.",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "Display",
 		"define": "display",
-		"doc": "Activated during completion"
+		"doc": "Activated during completion.",
+		"links": ["https://haxe.org/manual/cr-completion.html"]
 	},
 	{
 		"name": "DisplayStdin",
 		"define": "display_stdin",
-		"doc": "Read the contents of a file specified in --display from standard input"
+		"doc": "Read the contents of a file specified in `--display` from standard input."
 	},
 	{
 		"name": "DllExport",
 		"define": "dll_export",
-		"doc": "GenCPP experimental linking",
+		"doc": "GenCPP experimental linking.",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "DllImport",
 		"define": "dll_import",
-		"doc": "Handle Haxe-generated .NET dll imports",
+		"doc": "Handle Haxe-generated .NET DLL imports.",
 		"platforms": ["cs"]
 	},
 	{
 		"name": "DocGen",
 		"define": "doc_gen",
-		"doc": "Do not perform any removal/change in order to correctly generate documentation"
+		"doc": "Do not perform any removal/change in order to correctly generate documentation."
 	},
 	{
 		"name": "Dump",
 		"define": "dump",
-		"doc": "<mode:pretty|record|position|legacy> Dump typed AST in dump subdirectory using specified mode or non-prettified default"
+		"doc": "Dump typed AST in dump subdirectory using specified mode or non-prettified default.",
+		"params": ["mode: pretty | record | position | legacy"]
 	},
 	{
 		"name": "DumpDependencies",
 		"define": "dump_dependencies",
-		"doc": "Dump the classes dependencies in a dump subdirectory"
+		"doc": "Dump the classes dependencies in a dump subdirectory."
 	},
 	{
 		"name": "DumpIgnoreVarIds",
 		"define": "dump_ignore_var_ids",
-		"doc": "Remove variable IDs from non-pretty dumps (helps with diff)"
+		"doc": "Remove variable IDs from non-pretty dumps (helps with diff)."
 	},
 	{
 		"name": "DynamicInterfaceClosures",
 		"define": "dynamic_interface_closures",
-		"doc": "Use slow path for interface closures to save space",
+		"doc": "Use slow path for interface closures to save space.",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "EraseGenerics",
 		"define": "erase_generics",
-		"doc": "Erase generic classes on C#",
+		"doc": "Erase generic classes on C#.",
 		"platforms": ["cs"]
 	},
 	{
 		"name": "EvalCallStackDepth",
 		"define": "eval_call_stack_depth",
-		"doc": "Set maximum call stack depth for eval. Default: 1000.",
-		"platforms": ["eval"]
+		"doc": "Set maximum call stack depth for eval. (default: 1000)",
+		"platforms": ["eval"],
+		"params": ["depth"]
 	},
 	{
 		"name": "EvalDebugger",
 		"define": "eval_debugger",
-		"doc": "Support debugger in macro/interp mode. Allows host:port value to open a socket. Implies eval_stack.",
+		"doc": "Support debugger in macro/interp mode. Allows `host:port` value to open a socket. Implies eval_stack.",
 		"platforms": ["eval"]
 	},
 	{
 		"name": "EvalStack",
 		"define": "eval_stack",
-		"doc": "Record stack information in macro/interp mode",
+		"doc": "Record stack information in macro/interp mode.",
 		"platforms": ["eval"]
 	},
 	{
@@ -155,201 +161,207 @@
 	{
 		"name": "FastCast",
 		"define": "fast_cast",
-		"doc": "Enables an experimental casts cleanup on C# and Java",
+		"doc": "Enables an experimental casts cleanup on C# and Java.",
 		"platforms": ["cs", "java"]
 	},
 	{
 		"name": "Fdb",
 		"define": "fdb",
-		"doc": "Enable full flash debug infos for FDB interactive debugging",
+		"doc": "Enable full flash debug infos for FDB interactive debugging.",
 		"platforms": ["flash"]
 	},
 	{
 		"name": "FileExtension",
 		"define": "file_extension",
-		"doc": "Output filename extension for cpp source code",
+		"doc": "Output filename extension for cpp source code.",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "FlashStrict",
 		"define": "flash_strict",
-		"doc": "More strict typing for flash target",
+		"doc": "More strict typing for flash target.",
 		"platforms": ["flash"]
 	},
 	{
 		"name": "FlashUseStage",
 		"define": "flash_use_stage",
-		"doc": "Keep the SWF library initial stage",
+		"doc": "Keep the SWF library initial stage.",
 		"platforms": ["flash"]
 	},
 	{
 		"devcomment": "force_lib_check is only here as a debug facility - compiler checking allows errors to be found more easily",
 		"name": "ForceLibCheck",
 		"define": "force_lib_check",
-		"doc": "Force the compiler to check -net-lib and -java-lib added classes (internal)",
+		"doc": "Force the compiler to check `--net-lib` and `–-java-lib` added classes (internal).",
 		"platforms": ["cs", "java"]
 	},
 	{
 		"name": "ForceNativeProperty",
 		"define": "force_native_property",
-		"doc": "Tag all properties with :nativeProperty metadata for 3.1 compatibility",
+		"doc": "Tag all properties with `:nativeProperty` metadata for 3.1 compatibility.",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "GencommonDebug",
 		"define": "gencommon_debug",
-		"doc": "GenCommon internal",
+		"doc": "GenCommon internal.",
 		"platforms": ["cs", "java"]
 	},
 	{
 		"name": "Haxe3Compat",
 		"define": "haxe3compat",
-		"doc": "Gives warnings about transition from Haxe 3.x to Haxe 4.0"
+		"doc": "Gives warnings about transition from Haxe 3.x to Haxe 4.0."
 	},
 	{
 		"name": "HaxeBoot",
 		"define": "haxe_boot",
-		"doc": "Given the name 'haxe' to the flash boot class instead of a generated name",
+		"doc": "Give the name 'haxe' to the flash boot class instead of a generated name.",
 		"platforms": ["flash"]
 	},
 	{
 		"name": "HaxeVer",
 		"define": "haxe_ver",
-		"doc": "The current Haxe version value as decimal number. E.g. 4.000 for 4.0.0"
+		"doc": "The current Haxe version value as decimal number. E.g. 3.407 for 3.4.7."
 	},
 	{
 		"name": "Haxe",
 		"define": "haxe",
-		"doc": "The current Haxe version value in SemVer format"
+		"doc": "The current Haxe version value in SemVer format."
 	},
 	{
 		"name": "HxcppApiLevel",
 		"define": "hxcpp_api_level",
-		"doc": "Provided to allow compatibility between hxcpp versions",
+		"doc": "Provided to allow compatibility between hxcpp versions.",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "HxcppGcGenerational",
-		"define": "HXCPP_GC_GENERATIONAL",
-		"doc": "Experimental Garbage Collector",
+		"define": "hxcpp_gc_generational",
+		"doc": "Experimental Garbage Collector.",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "HxcppDebugger",
-		"define": "HXCPP_DEBUGGER",
-		"doc": "Include additional information for HXCPP_DEBUGGER",
+		"define": "hxcpp_debugger",
+		"doc": "Include additional information for hxcpp_debugger.",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "HxcppSmartStings",
 		"define": "hxcpp_smart_strings",
-		"doc": "Use wide strings in hxcpp (Turned on by default unless `-D disable_unicode_strings` is specified)",
+		"doc": "Use wide strings in hxcpp. (Turned on by default unless `-D disable_unicode_strings` is specified.)",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "IncludePrefix",
 		"define": "include_prefix",
-		"doc": "prepend path to generated include files",
+		"doc": "Prepend path to generated include files.",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "Interp",
 		"define": "interp",
-		"doc": "The code is compiled to be run with --interp"
+		"doc": "The code is compiled to be run with `--interp`."
 	},
 	{
 		"name": "JavaVer",
 		"define": "java_ver",
-		"doc": "<version:5-7> Sets the Java version to be targeted",
-		"platforms": ["java"]
+		"doc": "Sets the Java version to be targeted.",
+		"platforms": ["java"],
+		"params": ["version: 5-7"]
 	},
 	{
 		"name": "JsClassic",
 		"define": "js_classic",
-		"doc": "Don't use a function wrapper and strict mode in JS output",
+		"doc": "Don't use a function wrapper and strict mode in JS output.",
 		"platforms": ["js"]
 	},
 	{
 		"name": "JsEs",
 		"define": "js_es",
-		"doc": "Generate JS compliant with given ES standard version (default 5)",
+		"doc": "Generate JS compliant with given ES standard version. (default: 5)",
 		"platforms": ["js"],
-		"params": ["version number"]
+		"params": ["version number"],
+		"links": ["https://haxe.org/manual/target-javascript-es6.html"]
 	},
 	{
 		"name": "JsEnumsAsArrays",
 		"define": "js_enums_as_arrays",
-		"doc": "Generate enum representation as array instead of as object",
+		"doc": "Generate enum representation as array instead of as object.",
 		"platforms": ["js"]
 	},
 	{
 		"name": "JsUnflatten",
 		"define": "js_unflatten",
-		"doc": "Generate nested objects for packages and types",
+		"doc": "Generate nested objects for packages and types.",
 		"platforms": ["js"]
 	},
 	{
 		"name": "JsSourceMap",
 		"define": "js_source_map",
-		"doc": "Generate JavaScript source map even in non-debug mode",
+		"doc": "Generate JavaScript source map even in non-debug mode.",
 		"platforms": ["js"]
 	},
 	{
 		"name": "Jvm",
 		"define": "jvm",
-		"doc": "Generate jvm directly",
+		"doc": "Generate jvm directly.",
 		"platforms": ["java"]
 	},
 	{
 		"name": "SourceMap",
 		"define": "source_map",
-		"doc": "Generate source map for compiled files (Currently supported for php only)",
+		"doc": "Generate source map for compiled files.",
 		"platforms": ["php"]
 	},
 	{
 		"name": "KeepOldOutput",
 		"define": "keep_old_output",
-		"doc": "Keep old source files in the output directory",
+		"doc": "Keep old source files in the output directory.",
 		"platforms": ["cs", "java"]
 	},
 	{
 		"name": "LoopUnrollMaxCost",
 		"define": "loop_unroll_max_cost",
-		"doc": "Maximum cost (number of expressions * iterations) before loop unrolling is canceled (default 250)"
+		"doc": "Maximum cost (number of expressions * iterations) before loop unrolling is canceled. (default: 250)",
+		"params": ["cost"]
 	},
 	{
 		"name": "LuaJit",
 		"define": "lua_jit",
-		"doc": "Enable the jit compiler for lua (version 5.2 only)",
+		"doc": "Enable the jit compiler for lua (version 5.2 only).",
 		"platforms": ["lua"]
 	},
 	{
 		"name": "LuaVanilla",
 		"define": "lua_vanilla",
-		"doc": "Generate code lacking compiled extern lib support (e.g. utf8)",
+		"doc": "Generate code lacking compiled extern lib support (e.g. utf8).",
 		"platforms": ["lua"]
 	},
 	{
 		"name": "LuaVer",
 		"define": "lua_ver",
-		"doc": "The lua version to target",
-		"platforms": ["lua"]
+		"doc": "The lua version to target.",
+		"platforms": ["lua"],
+		"params": ["version"]
 	},
 	{
 		"name": "Macro",
 		"define": "macro",
-		"doc": "Defined when code is compiled in the macro context"
+		"doc": "Defined when code is compiled in the macro context.",
+		"links": ["https://haxe.org/manual/macro.html"]
 	},
 	{
 		"name": "MacroTimes",
 		"define": "macro_times",
-		"doc": "Display per-macro timing when used with --times"
+		"doc": "Display per-macro timing when used with `--times`."
 	},
 	{
 		"name": "NetVer",
 		"define": "net_ver",
-		"doc": "<version:20-45> Sets the .NET version to be targeted",
-		"platforms": ["cs"]
+		"doc": "Sets the .NET version to be targeted.",
+		"platforms": ["cs"],
+		"params": ["version: 20-45"]
 	},
 	{
 		"name": "NetcoreVer",
@@ -360,96 +372,98 @@
 	{
 		"name": "NetTarget",
 		"define": "net_target",
-		"doc": "<name> Sets the .NET target. Defaults to \"net\". netcore, xbox, micro (Micro Framework), compact (Compact Framework) are some valid values",
-		"platforms": ["cs"]
+		"doc": "Sets the .NET target. `netcore` (.NET core), `xbox`, `micro` (Micro Framework), `compact` (Compact Framework) are some valid values. (default: `net`)",
+		"platforms": ["cs"],
+		"params": ["name"]
 	},
 	{
 		"name": "NekoSource",
 		"define": "neko_source",
-		"doc": "Output neko source instead of bytecode",
+		"doc": "Output neko source instead of bytecode.",
 		"platforms": ["neko"]
 	},
 	{
 		"name": "NekoV1",
 		"define": "neko_v1",
-		"doc": "Keep Neko 1.x compatibility",
+		"doc": "Keep Neko 1.x compatibility.",
 		"platforms": ["neko"]
 	},
 	{
 		"name": "NetworkSandbox",
 		"define": "network-sandbox",
-		"doc": "Use local network sandbox instead of local file access one",
+		"doc": "Use local network sandbox instead of local file access one.",
 		"platforms": ["flash"]
 	},
 	{
 		"name": "NoCompilation",
 		"define": "no-compilation",
-		"doc": "Disable final compilation",
+		"doc": "Disable final compilation.",
 		"platforms": ["cs", "java", "cpp", "hl"]
 	},
 	{
 		"name": "NoCOpt",
 		"define": "no_copt",
-		"doc": "Disable completion optimization (for debug purposes)"
+		"doc": "Disable completion optimization (for debug purposes)."
 	},
 	{
 		"name": "NoDebug",
 		"define": "no_debug",
-		"doc": "Remove all debug macros from cpp output"
+		"doc": "Remove all debug macros from cpp output."
 	},
 	{
 		"name": "NoDeprecationWarnings",
 		"define": "no-deprecation-warnings",
-		"doc": "Do not warn if fields annotated with @:deprecated are used"
+		"doc": "Do not warn if fields annotated with `@:deprecated` are used."
 	},
 	{
 		"name": "NoFlashOverride",
 		"define": "no-flash-override",
-		"doc": "Change overrides on some basic classes into HX suffixed methods, flash only",
+		"doc": "Change overrides on some basic classes into HX suffixed methods",
 		"platforms": ["flash"]
 	},
 	{
 		"name": "NoOpt",
 		"define": "no_opt",
-		"doc": "Disable optimizations"
+		"doc": "Disable optimizations."
 	},
 	{
 		"name": "NoInline",
 		"define": "no_inline",
-		"doc": "Disable inlining"
+		"doc": "Disable inlining.",
+		"links": ["https://haxe.org/manual/class-field-inline.html"]
 	},
 	{
 		"name": "NoRoot",
 		"define": "no_root",
-		"doc": "Generate top-level types into haxe.root namespace",
+		"doc": "Generate top-level types into the `haxe.root` namespace.",
 		"platforms": ["cs"]
 	},
 	{
 		"name": "NoMacroCache",
 		"define": "no_macro_cache",
-		"doc": "Disable macro context caching"
+		"doc": "Disable macro context caching."
 	},
 	{
 		"name": "NoSwfCompress",
 		"define": "no_swf_compress",
-		"doc": "Disable SWF output compression",
+		"doc": "Disable SWF output compression.",
 		"platforms": ["flash"]
 	},
 	{
 		"name": "NoTraces",
 		"define": "no_traces",
-		"doc": "Disable all trace calls"
+		"doc": "Disable all trace calls."
 	},
 	{
 		"name": "Objc",
 		"define": "objc",
-		"doc": "Sets the hxcpp output to objective-c++ classes. Must be defined for interop",
+		"doc": "Sets the hxcpp output to Objective-C++ classes. Must be defined for interop.",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "OldConstructorInline",
 		"define": "old-constructor-inline",
-		"doc": "Use old constructor inlining logic (from haxe 3.4.2) instead of the reworked version."
+		"doc": "Use old constructor inlining logic (from Haxe 3.4.2) instead of the reworked version."
 	},
 	{
 		"name": "OldErrorFormat",
@@ -460,157 +474,165 @@
 		"name": "PhpPrefix",
 		"define": "php_prefix",
 		"doc": "Root namespace for generated php classes. E.g. if compiled with`-D php-prefix=some.sub`, then all classes will be generated in `\\some\\sub` namespace.",
-		"platforms": ["php"]
+		"platforms": ["php"],
+		"params": ["dot-separated namespace"]
 	},
 	{
 		"name": "PhpLib",
 		"define": "php_lib",
 		"doc": "Select the name for the php lib folder.",
-		"platforms": ["php"]
+		"platforms": ["php"],
+		"params": ["folder name"]
 	},
 	{
 		"name": "PhpFront",
 		"define": "php_front",
-		"doc": "Select the name for the php front file (by default: `index.php`).",
-		"platforms": ["php"]
+		"doc": "Select the name for the php front file. (default: `index.php`)",
+		"platforms": ["php"],
+		"params": ["filename"]
 	},
 	{
 		"name": "PythonVersion",
 		"define": "python_version",
-		"doc": "The python version to target (default 3.3)",
-		"platforms": ["python"]
+		"doc": "The python version to target. (default: 3.3)",
+		"platforms": ["python"],
+		"params": ["version"]
 	},
 	{
 		"name": "RealPosition",
 		"define": "real_position",
-		"doc": "Disables Haxe source mapping when targetting C#, removes position comments in Java and Php output",
+		"doc": "Disables Haxe source mapping when targetting C#, removes position comments in Java and Php output.",
 		"platforms": ["cs", "java", "php"]
 	},
 	{
 		"name": "ReplaceFiles",
 		"define": "replace_files",
-		"doc": "GenCommon internal",
+		"doc": "GenCommon internal.",
 		"platforms": ["cs", "java"]
 	},
 	{
 		"name": "Scriptable",
 		"define": "scriptable",
-		"doc": "GenCPP internal",
+		"doc": "GenCPP internal.",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "ShallowExpose",
 		"define": "shallow-expose",
-		"doc": "Expose types to surrounding scope of Haxe generated closure without writing to window object",
+		"doc": "Expose types to surrounding scope of Haxe generated closure without writing to window object.",
 		"platforms": ["js"]
 	},
 	{
 		"name": "SourceHeader",
 		"define": "source-header",
-		"doc": "Print value as comment on top of generated files, use '' value to disable"
+		"doc": "Print value as comment on top of generated files, use '' value to disable."
 	},
 	{
 		"name": "SourceMapContent",
 		"define": "source-map-content",
-		"doc": "Include the hx sources as part of the JS source map",
+		"doc": "Include the Haxe sources as part of the JS source map.",
 		"platforms": ["js"]
 	},
 	{
 		"name": "Static",
 		"define": "static",
-		"doc": "Defined if the current target is static"
+		"doc": "Defined if the current target is static."
 	},
 	{
 		"name": "Swc",
 		"define": "swc",
-		"doc": "Output a SWC instead of a SWF",
+		"doc": "Output a SWC instead of a SWF.",
 		"platforms": ["flash"]
 	},
 	{
 		"name": "SwfCompressLevel",
 		"define": "swf_compress_level",
-		"doc": "<level:1-9> Set the amount of compression for the SWF output",
-		"platforms": ["flash"]
+		"doc": "Set the amount of compression for the SWF output.",
+		"platforms": ["flash"],
+		"params": ["level: 1-9"]
 	},
 	{
 		"name": "SwfDebugPassword",
 		"define": "swf_debug_password",
-		"doc": "Set a password for debugging",
-		"platforms": ["flash"]
+		"doc": "Set a password for debugging.",
+		"platforms": ["flash"],
+		"params": ["password"]
 	},
 	{
 		"name": "SwfDirectBlit",
 		"define": "swf_direct_blit",
-		"doc": "Use hardware acceleration to blit graphics",
+		"doc": "Use hardware acceleration to blit graphics.",
 		"platforms": ["flash"]
 	},
 	{
 		"name": "SwfGpu",
 		"define": "swf_gpu",
-		"doc": "Use GPU compositing features when drawing graphics",
+		"doc": "Use GPU compositing features when drawing graphics.",
 		"platforms": ["flash"]
 	},
 	{
 		"name": "SwfMetadata",
 		"define": "swf_metadata",
-		"doc": "<file> Include contents of <file> as metadata in the swf",
-		"platforms": ["flash"]
+		"doc": "Include contents of the given file as metadata in the SWF.",
+		"platforms": ["flash"],
+		"params": ["file"]
 	},
 	{
 		"name": "SwfPreloaderFrame",
 		"define": "swf_preloader_frame",
-		"doc": "Insert empty first frame in swf",
+		"doc": "Insert empty first frame in SWF.",
 		"platforms": ["flash"]
 	},
 	{
 		"name": "SwfProtected",
 		"define": "swf_protected",
-		"doc": "Compile Haxe private as protected in the SWF instead of public",
+		"doc": "Compile Haxe `private` as `protected` in the SWF instead of `public`.",
 		"platforms": ["flash"]
 	},
 	{
 		"name": "SwfScriptTimeout",
 		"define": "swf_script_timeout",
-		"doc": "Maximum ActionScript processing time before script stuck dialog box displays (in seconds)",
-		"platforms": ["flash"]
+		"doc": "Maximum ActionScript processing time before script stuck dialog box displays.",
+		"platforms": ["flash"],
+		"params": ["time in seconds"]
 	},
 	{
 		"name": "SwfUseDoAbc",
 		"define": "swf_use_doabc",
-		"doc": "Use DoAbc swf-tag instead of DoAbcDefine",
+		"doc": "Use `DoAbc` SWF-tag instead of `DoAbcDefine`.",
 		"platforms": ["flash"]
 	},
 	{
 		"name": "Sys",
 		"define": "sys",
-		"doc": "Defined for all system platforms"
+		"doc": "Defined for all system platforms."
 	},
 	{
 		"name": "Unsafe",
 		"define": "unsafe",
-		"doc": "Allow unsafe code when targeting C#",
+		"doc": "Allow unsafe code when targeting C#.",
 		"platforms": ["cs"]
 	},
 	{
 		"name": "UseNekoc",
 		"define": "use_nekoc",
-		"doc": "Use nekoc compiler instead of internal one",
+		"doc": "Use `nekoc` compiler instead of the internal one.",
 		"platforms": ["neko"]
 	},
 	{
 		"name": "Utf16",
 		"define": "utf16",
-		"doc": "Defined for all platforms that have utf16 encoding with ucs2 api"
+		"doc": "Defined for all platforms that use UTF-16 string encoding with UCS-2 API."
 	},
 	{
 		"name": "Vcproj",
 		"define": "vcproj",
-		"doc": "GenCPP internal",
+		"doc": "GenCPP internal.",
 		"platforms": ["cpp"]
 	},
 	{
 		"name": "WarnVarShadowing",
 		"define": "warn_var_shadowing",
-		"doc": "Warn about shadowing variable declarations"
+		"doc": "Warn about shadowing variable declarations."
 	}
 ]

src/core/define.ml

@@ -12,14 +12,19 @@ let get_documentation_list() =
 		let d = Obj.magic i in
 		if d <> Last then begin
 			let t, (doc,flags) = infos d in
-			let pfs = ref [] in
+			let params = ref [] and pfs = ref [] in
 			List.iter (function
-			| HasParam s -> () (* TODO *)
-			| Platforms pl -> pfs := pl @ !pfs;
+				| HasParam s -> params := s :: !params
+				| Platforms fl -> pfs := fl @ !pfs
+				| Link _ -> ()
 			) flags;
+			let params = (match List.rev !params with
+				| [] -> ""
+				| l -> "<" ^ String.concat ">, <" l ^ "> "
+			) in
 			let pfs = platform_list_help (List.rev !pfs) in
 			if String.length t > !m then m := String.length t;
-			((String.concat "-" (ExtString.String.nsplit t "_")),doc ^ pfs) :: (loop (i + 1))
+			((String.concat "-" (ExtString.String.nsplit t "_")),params ^ doc ^ pfs) :: (loop (i + 1))
 		end else
 			[]
 	in

src/core/display/completionItem.ml

@@ -653,14 +653,15 @@ let to_json ctx item =
 				| TTypeParameter -> "TTypeParameter"
 				| TVariable -> "TVariable"
 			in
-			let rec loop internal params platforms targets l = match l with
-				| HasParam s :: l -> loop internal (s :: params) platforms targets l
-				| Platforms pls :: l -> loop internal params ((List.map platform_name pls) @ platforms) targets l
-				| UsedOn usages :: l -> loop internal params platforms ((List.map usage_to_string usages) @ targets) l
-				| UsedInternally :: l -> loop true params platforms targets l
-				| [] -> internal,params,platforms,targets
+			let rec loop internal params platforms targets links l = match l with
+				| HasParam s :: l -> loop internal (s :: params) platforms targets links l
+				| Platforms pls :: l -> loop internal params ((List.map platform_name pls) @ platforms) targets links l
+				| UsedOn usages :: l -> loop internal params platforms ((List.map usage_to_string usages) @ targets) links l
+				| UsedInternally :: l -> loop true params platforms targets links l
+				| Link url :: l -> loop internal params platforms targets (url :: links) l
+				| [] -> internal,params,platforms,targets,links
 			in
-			let internal,params,platforms,targets = loop false [] [] [] params in
+			let internal,params,platforms,targets,links = loop false [] [] [] [] params in
 			"Metadata",jobject [
 				"name",jstring name;
 				"doc",jstring doc;
@@ -668,6 +669,7 @@ let to_json ctx item =
 				"platforms",jlist jstring platforms;
 				"targets",jlist jstring targets;
 				"internal",jbool internal;
+				"links",jlist jstring links;
 			]
 		| ITKeyword kwd ->"Keyword",jobject [
 			"name",jstring (s_keyword kwd)

src/core/meta.ml

@@ -41,10 +41,11 @@ let get_documentation d =
 			| Platforms fl -> pfs := fl @ !pfs
 			| UsedOn ul -> used := ul @ !used
 			| UsedInternally -> assert false
+			| Link _ -> ()
 		) flags;
 		let params = (match List.rev !params with
 			| [] -> ""
-			| l -> "(" ^ String.concat "," l ^ ")"
+			| l -> "(<" ^ String.concat ">, <" l ^ ">) "
 		) in
 		let pfs = platform_list_help (List.rev !pfs) in
 		let str = "@" ^ t in

src/prebuild/main.ml

@@ -50,6 +50,13 @@ let as_bool = function
 	| JBool b -> Some b
 	| _ -> None
 
+let as_links = function
+	| JArray s -> Some (List.map (function
+			| JString s -> s
+			| _ -> raise (Prebuild_error "link should be a string")
+		) s)
+	| _ -> None
+
 let get_optional_field name map default fields =
 	try
 		let field = List.find (fun (n, _) -> n = name) fields in
@@ -71,11 +78,12 @@ let parse_define json =
 		| JObject fl -> fl
 		| _ -> raise (Prebuild_error "not an object")
 	in
-	(*name*) get_field "name" as_string fields,
-	(*define*) get_field "define" as_string fields,
-	(*doc*) get_field "doc" as_string fields,
-	(*params*) get_optional_field "params" as_params [] fields,
-	(*platforms*) get_optional_field "platforms" as_platforms [] fields
+	(* name *) get_field "name" as_string fields,
+	(* define *) get_field "define" as_string fields,
+	(* doc *) get_field "doc" as_string fields,
+	(* params *) get_optional_field "params" as_params [] fields,
+	(* platforms *) get_optional_field "platforms" as_platforms [] fields,
+	(* links *) get_optional_field "links" as_links [] fields
 
 let parse_meta json =
 	let fields = match json with
@@ -88,7 +96,8 @@ let parse_meta json =
 	(* params *) get_optional_field "params" as_params [] fields,
 	(* platforms *) get_optional_field "platforms" as_platforms [] fields,
 	(* targets *) get_optional_field "targets" as_targets [] fields,
-	(* internal *) get_optional_field "internal" as_bool false fields
+	(* internal *) get_optional_field "internal" as_bool false fields,
+	(* links *) get_optional_field "links" as_links [] fields
 
 let parse_file_array path map =
 	let file = open_in path in
@@ -106,27 +115,30 @@ let gen_platforms = function
 
 let gen_params = List.map (function param -> "HasParam \"" ^ param ^ "\"" )
 
+let gen_links = List.map (function link -> "Link \"" ^ link ^ "\"" )
+
 let gen_define_type defines =
-	String.concat "\n" (List.map (function (name, _, _, _, _) -> "\t| " ^ name) defines)
+	String.concat "\n" (List.map (function (name, _, _, _, _, _) -> "\t| " ^ name) defines)
 
 let gen_define_info defines =
 	let define_str = List.map (function
-		(name, define, doc, params, platforms) ->
+		(name, define, doc, params, platforms, links) ->
 			let platforms_str = gen_platforms platforms in
 			let params_str = gen_params params in
-			"\t| " ^ name ^ " -> \"" ^ define ^ "\",(" ^ (Printf.sprintf "%S" doc) ^ ",[" ^ (String.concat "; " (platforms_str @ params_str)) ^ "])"
+			let links_str = gen_links links in
+			"\t| " ^ name ^ " -> \"" ^ define ^ "\",(" ^ (Printf.sprintf "%S" doc) ^ ",[" ^ (String.concat "; " (platforms_str @ params_str @ links_str)) ^ "])"
 	) defines in
 	String.concat "\n" define_str
 
 let gen_meta_type metas =
 	String.concat "\n" (List.map (function
-		| ("InlineConstructorArgument", _, _, _, _, _, _) -> "\t| InlineConstructorArgument of int * int"
-		| (name, _, _, _, _, _, _) -> "\t| " ^ name
+		| ("InlineConstructorArgument", _, _, _, _, _, _, _) -> "\t| InlineConstructorArgument of int * int"
+		| (name, _, _, _, _, _, _, _) -> "\t| " ^ name
 	) metas)
 
 let gen_meta_info metas =
 	let meta_str = List.map (function
-		(name, metadata, doc, params, platforms, targets, internal) ->
+		(name, metadata, doc, params, platforms, targets, internal, links) ->
 			let platforms_str = gen_platforms platforms in
 			let params_str = gen_params params in
 			let targets_str = (match targets with
@@ -134,12 +146,13 @@ let gen_meta_info metas =
 				| targets -> ["UsedOn [" ^ (String.concat ";" targets) ^ "]"]
 			) in
 			let internal_str = if internal then ["UsedInternally"] else [] in
+			let links_str = gen_links links in
 			let name = (match name with
 				(* this is a hacky, I know *)
 				| "InlineConstructorArgument" -> "InlineConstructorArgument _"
 				| _ -> name
 			) in
-			"\t| " ^ name ^ " -> \"" ^ metadata ^ "\",(" ^ (Printf.sprintf "%S" doc) ^ ",[" ^ (String.concat "; " (platforms_str @ params_str @ targets_str @ internal_str)) ^ "])"
+			"\t| " ^ name ^ " -> \"" ^ metadata ^ "\",(" ^ (Printf.sprintf "%S" doc) ^ ",[" ^ (String.concat "; " (platforms_str @ params_str @ targets_str @ internal_str @ links_str)) ^ "])"
 	) metas in
 	String.concat "\n" meta_str
 
@@ -153,6 +166,7 @@ open Globals
 type define_parameter =
 	| HasParam of string
 	| Platforms of platform list
+	| Link of string
 
 "
 
@@ -176,6 +190,7 @@ type meta_parameter =
 	| Platforms of platform list
 	| UsedOn of meta_usage list
 	| UsedInternally
+	| Link of string
 
 "
 

tests/display/src/cases/Issue5796.hx

@@ -11,7 +11,7 @@ class Issue5796 extends DisplayTestCase {
 		}
 	**/
 	function test() {
-		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field", metadataDoc(pos(1)));
+		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field.", metadataDoc(pos(1)));
 		eq("Int", type(pos(2)));
 	}
 }

tests/display/src/cases/Metadata.hx

@@ -33,7 +33,7 @@ class Metadata extends DisplayTestCase {
 		class Some { }
 	**/
 	function testHover() {
-		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field", metadataDoc(pos(1)));
+		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field.", metadataDoc(pos(1)));
 	}
 
 	/**
@@ -94,9 +94,9 @@ class Metadata extends DisplayTestCase {
 		}
 	**/
 	function testExpression5() {
-		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field", metadataDoc(pos(1)));
-		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field", metadataDoc(pos(2)));
-		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field", metadataDoc(pos(3)));
+		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field.", metadataDoc(pos(1)));
+		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field.", metadataDoc(pos(2)));
+		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field.", metadataDoc(pos(3)));
 	}
 
 	/**
@@ -105,8 +105,8 @@ class Metadata extends DisplayTestCase {
 		}
 	**/
 	function testExpression6() {
-		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field", metadataDoc(pos(1)));
-		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field", metadataDoc(pos(2)));
-		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field", metadataDoc(pos(3)));
+		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field.", metadataDoc(pos(1)));
+		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field.", metadataDoc(pos(2)));
+		eq("Marks a class or class field as generic so each type parameter combination generates its own type/field.", metadataDoc(pos(3)));
 	}
 }