Backport define and metadata docs feature (#573)

Add support for documentation field with metadata and defines

schema.json

@@ -47,6 +47,21 @@
 			},
 			"additionalProperties": false
 		},
+		"documentation": {
+			"type": "object",
+			"description": "Project's documentation resources",
+			"properties": {
+				"defines": {
+					"type": "string",
+					"description": "Relative path to json file describing this project's custom defines"
+				},
+				"metadata": {
+					"type": "string",
+					"description": "Relative path to json file describing this project's custom metadata"
+				}
+			},
+			"additionalProperties": false
+		},
 		"releasenote": {
 			"description": "Short description of changes made in this version",
 			"type": "string"

src/haxelib/Data.hx

@@ -171,7 +171,35 @@ typedef Infos = {
 	var contributors : Array<String>;
 	@:optional var tags : Array<String>;
 	@:optional var dependencies : Dependencies;
-	@:optional var main:String;
+	@:optional var main : String;
+	@:optional var documentation : LibraryDocumentation;
+}
+
+/** Documentation data held in the `documentation` field of the `haxelib.json` file. **/
+typedef LibraryDocumentation = {
+	@:optional var defines : String;
+	@:optional var metadata : String;
+}
+
+/** Metadata documentation data as should be declared in the json linked in the
+ * `documentation.metadata` field of the `haxelib.json` file. **/
+typedef MetadataDocumentation = {
+	var metadata : String;
+	var doc : String;
+	@:optional var platforms : Array<String>;
+	@:optional var params : Array<String>;
+	@:optional var targets : Array<String>;
+	@:optional var links : Array<String>;
+}
+
+/** Define documentation data as should be declared in the json linked in the
+ * `documentation.defines` field of the `haxelib.json` file. **/
+typedef DefineDocumentation = {
+	var define : String;
+	var doc : String;
+	@:optional var platforms : Array<String>;
+	@:optional var params : Array<String>;
+	@:optional var links : Array<String>;
 }
 
 @:enum abstract License(String) to String {
@@ -330,6 +358,48 @@ class Data {
 		}
 	}
 
+	/** Throws an exception if files referenced in `documentation` field of an `infos` do not exist or are invalid **/
+	public static function checkDocumentation( zip : List<Entry>, infos : Infos ) {
+		if (infos.documentation == null) return;
+
+		var hasDefines = infos.documentation.defines == null;
+		var hasMetadata = infos.documentation.metadata == null;
+		if (!hasDefines && !hasMetadata) return;
+
+		var basePath = Data.locateBasePath(zip);
+		var definesPath = hasDefines ? null : basePath + infos.documentation.defines;
+		var metadataPath = hasMetadata ? null : basePath + infos.documentation.metadata;
+		var definesFound = false;
+		var metadataFound = false;
+
+		for (f in zip) {
+			if (hasDefines && StringTools.startsWith(f.fileName, definesPath)) {
+				definesFound = true;
+				try {
+					var jsondata = Reader.unzip(f).toString();
+					var defines:Array<DefineDocumentation> = Json.parse(jsondata);
+					Validator.validate(defines);
+				} catch (_:Dynamic) {
+					throw 'Defines documentation json file does not match expected format';
+				}
+			} else if (hasMetadata && StringTools.startsWith(f.fileName, metadataPath)) {
+				metadataFound = true;
+				try {
+					var jsondata = Reader.unzip(f).toString();
+					var metas:Array<MetadataDocumentation> = Json.parse(jsondata);
+					Validator.validate(metas);
+				} catch (_:Dynamic) {
+					throw 'Metadata documentation json file does not match expected format';
+				}
+			}
+
+			if ((!hasDefines || definesFound) && (!hasMetadata || metadataFound)) break;
+		}
+
+		if (hasDefines && !definesFound) throw 'Json file `${infos.documentation.defines}` not found';
+		if (hasMetadata && !metadataFound) throw 'Json file `${infos.documentation.metadata}` not found';
+	}
+
 	public static function readData( jsondata: String, check : CheckLevel ) : Infos {
 		var doc:Infos =
 			try Json.parse(jsondata)

src/haxelib/client/Main.hx

@@ -634,6 +634,7 @@ class Main {
 
 		var infos = Data.readInfos(zip,true);
 		Data.checkClassPath(zip, infos);
+		Data.checkDocumentation(zip, infos);
 
 		var user:String = infos.contributors[0];
 
@@ -1502,6 +1503,25 @@ class Main {
 			Sys.println(dir);
 
 			Sys.println("-D " + d.project + "="+d.info.version);
+
+			if (d.info.documentation != null) {
+				var doc = d.info.documentation;
+
+				// we'll have to change this to "4.3.0" after the release
+				if (haxeVersion() >= SemVer.ofString("4.3.0-rc.1")) {
+					// custom defines if defined
+					if (doc.defines != null && doc.defines != "") {
+						var path = Path.join([d.dir, doc.defines]);
+						Sys.println('--macro registerDefinesDescriptionFile(\'$path\', \'${d.info.name}\')');
+					}
+
+					// custom metadatas if defined
+					if (doc.metadata != null && doc.metadata != "") {
+						var path = Path.join([d.dir, doc.metadata]);
+						Sys.println('--macro registerMetadataDescriptionFile(\'$path\', \'${d.info.name}\')');
+					}
+				}
+			}
 		}
 	}
 

test/libraries/libBadDefineJson/doc/defines.json

@@ -0,0 +1,5 @@
+[
+	{
+		"name": "Malformed define"
+	}
+]

test/libraries/libBadDefineJson/haxelib.json

@@ -0,0 +1,13 @@
+{
+	"name": "BadDefineJson",
+	"url" : "http://example.org",
+	"license": "GPL",
+	"tags": ["bar", "test"],
+	"description": "This project is an example of an haxelib project",
+	"version": "1.0.0",
+	"releasenote": "Initial release, everything is working correctly",
+	"documentation": {
+		"defines": "doc/defines.json"
+	},
+	"contributors": ["Bar"]
+}

test/libraries/libBadMetaJson/doc/meta.json

@@ -0,0 +1 @@
+This is not a json file

test/libraries/libBadMetaJson/haxelib.json

@@ -0,0 +1,13 @@
+{
+	"name": "BadMetaJson",
+	"url" : "http://example.org",
+	"license": "GPL",
+	"tags": ["bar", "test"],
+	"description": "This project is an example of an haxelib project",
+	"version": "1.0.0",
+	"releasenote": "Initial release, everything is working correctly",
+	"documentation": {
+		"metadata": "doc/meta.json"
+	},
+	"contributors": ["Bar"]
+}

test/libraries/libBadMetaJson2/doc/meta.json

@@ -0,0 +1,5 @@
+[
+	{
+		"name": "Malformed meta"
+	}
+]

test/libraries/libBadMetaJson2/haxelib.json

@@ -0,0 +1,13 @@
+{
+	"name": "BadMetaJson2",
+	"url" : "http://example.org",
+	"license": "GPL",
+	"tags": ["bar", "test"],
+	"description": "This project is an example of an haxelib project",
+	"version": "1.0.0",
+	"releasenote": "Initial release, everything is working correctly",
+	"documentation": {
+		"metadata": "doc/meta.json"
+	},
+	"contributors": ["Bar"]
+}

test/libraries/libDocumentationFiles/doc/defines.json

@@ -0,0 +1,13 @@
+[
+	{
+		"define": "test",
+		"doc": "Test define"
+	},
+	{
+		"define": "test2",
+		"doc": "Test define 2",
+		"platforms": ["eval"],
+		"params": ["foo"],
+		"links": ["https://example.com"]
+	}
+]

test/libraries/libDocumentationFiles/doc/meta.json

@@ -0,0 +1,14 @@
+[
+	{
+		"metadata": ":test",
+		"doc": "Some test metadata"
+	},
+	{
+		"metadata": ":test2",
+		"doc": "Some other test metadata",
+		"platforms": ["eval"],
+		"params": ["foo"],
+		"links": ["https://example.com"],
+		"targets": ["TClass", "TClassField"]
+	}
+]

test/libraries/libDocumentationFiles/haxelib.json

@@ -0,0 +1,14 @@
+{
+	"name": "DocumentationFiles",
+	"url" : "http://example.org",
+	"license": "GPL",
+	"tags": ["bar", "test"],
+	"description": "This project is an example of an haxelib project",
+	"version": "1.0.0",
+	"releasenote": "Initial release, everything is working correctly",
+	"documentation": {
+		"metadata": "doc/meta.json",
+		"defines": "doc/defines.json"
+	},
+	"contributors": ["Bar"]
+}

test/libraries/libMissingMetaJson/haxelib.json

@@ -0,0 +1,13 @@
+{
+	"name": "MissingMetaJson",
+	"url" : "http://example.org",
+	"license": "GPL",
+	"tags": ["bar", "test"],
+	"description": "This project is an example of an haxelib project",
+	"version": "1.0.0",
+	"releasenote": "Initial release, everything is working correctly",
+	"documentation": {
+		"metadata": "doc/meta.json"
+	},
+	"contributors": ["Bar"]
+}

test/tests/TestData.hx

@@ -103,6 +103,27 @@ class TestData extends TestBase {
 		assertEquals( ok, true );
 	}
 
+	public function testCheckDocumentation() {
+		var results = [
+			"DocumentationFiles" => true,
+			"BadMetaJson" => false,
+			"BadMetaJson2" => false,
+			"BadDefineJson" => false
+		];
+
+		for (r in results.keys()) {
+			var zip = Reader.readZip(new BytesInput(File.getBytes('test/libraries/lib$r.zip')));
+			var info = Data.readInfos(zip, CheckData);
+
+			try {
+				Data.checkDocumentation(zip,info);
+				assertTrue(results.get(r));
+			} catch (e:Dynamic) {
+				assertFalse(results.get(r));
+			}
+		}
+	}
+
 	public function testReadDataWithCheck() {
 		assertFalse( readDataOkay("bad json") );