Add support for typedefs that are conditionalized by platform

closes #257

CHANGELOG.md

@@ -1,10 +1,12 @@
-### 1.4.1 (to be released)
+### 1.5.0 (to be released)
 
 - added a "final" prefix for final classes and interfaces
 - added support for deprecation messages on types ([#261](https://github.com/HaxeFoundation/dox/issues/261))
 - added support for `@:noCompletion` implying `@:dox(hide)` ([#250](https://github.com/HaxeFoundation/dox/issues/250))
+- added support for typedefs that are conditionalized by platform ([#257](https://github.com/HaxeFoundation/dox/issues/257))
 - added a `--keep-field-order` argument ([#258](https://github.com/HaxeFoundation/dox/issues/258))
 - added tooltips with descriptions for compiler metadata ([#240](https://github.com/HaxeFoundation/dox/issues/240))
+- added the fully qualified path of types to tooltips
 - improved function type printing to use Haxe 4 syntax ([#273](https://github.com/HaxeFoundation/dox/issues/273))
 - fixed JS version being used if the node version is not supported (< 8.10.0)
 - fixed interfaces with multiple `extends` only showing the first one ([#260](https://github.com/HaxeFoundation/dox/issues/260))

src/dox/Api.hx

@@ -37,6 +37,11 @@ class Api {
 	**/
 	public var std = Std;
 
+	/**
+		Expose Lambda for theme.
+	**/
+	public var lambda = Lambda;
+
 	/**
 		Information about compiler metadata by name.
 	**/
@@ -157,15 +162,16 @@ class Api {
 	}
 
 	/**
-		Returns the first sentence of the documentation belonging to `infos`.
+		Returns the first sentence of the documentation belonging to `infos` as well as its dot path.
 	**/
 	public function getSentenceDesc(infos:TypeInfos):String {
+		var path = infos.path;
 		if (infos == null || infos.doc == null) {
-			return "";
+			return path;
 		}
 		var stripped = ~/<.+?>/g.replace(infos.doc, "").replace("\n", " ");
 		var sentence = ~/^(.*?[.?!]+)/;
-		return sentence.match(stripped) ? sentence.matched(1) : "";
+		return sentence.match(stripped) ? path + " - " + sentence.matched(1) : path;
 	}
 
 	public function getMetaDesc(meta:String):String {

src/dox/Processor.hx

@@ -1,5 +1,6 @@
 package dox;
 
+import haxe.Serializer;
 import haxe.rtti.CType;
 
 class Processor {
@@ -213,14 +214,40 @@ class Processor {
 				t.doc = processDoc(t.path, t.doc);
 				t.constructors.iter(processEnumField.bind(t.path));
 				makeFilePathRelative(t);
+
 			case TTypedecl(t):
 				config.setRootPath(t.path);
 				t.doc = processDoc(t.path, t.doc);
-				switch (t.type) {
-					case CAnonymous(fields): fields.iter(processClassField.bind(t.path));
-					default:
+
+				var mergedTypes = new Map<String, CType>();
+				for (platform => typeA in t.types) {
+					var found = false;
+					for (platforms => typeB in mergedTypes) {
+						if (Serializer.run(typeA) == Serializer.run(typeB)) {
+							mergedTypes.remove(platforms);
+							mergedTypes[platforms + ", " + platform] = typeB;
+							found = true;
+							break;
+						}
+					}
+					if (!found) {
+						mergedTypes[platform] = typeA;
+					}
 				}
+				t.types = mergedTypes;
+
+				function processFields(type:CType) {
+					switch (t.type) {
+						case CAnonymous(fields):
+							fields.iter(processClassField.bind(t.path));
+						default:
+					}
+				}
+				processFields(t.type);
+				t.types.iter(processFields);
+
 				makeFilePathRelative(t);
+
 			case TClassdecl(t):
 				config.setRootPath(t.path);
 				t.doc = processDoc(t.path, t.doc);
@@ -241,6 +268,7 @@ class Processor {
 						implementors.push(t);
 				}
 				makeFilePathRelative(t);
+
 			case TAbstractdecl(t):
 				config.setRootPath(t.path);
 				if (t.impl != null) {

test/dox/DoxTest.hx

@@ -374,3 +374,18 @@ class NoCompletion {
 
 @:noCompletion class NoCompletionType {}
 @:noCompletion @:dox(show) class NoCompletionButDoxShowType {}
+
+/**
+	This typedef has different implementations per target.
+**/
+typedef PlatformConditionalized = #if cpp {
+	/**
+		It a int
+	**/
+	var i:Int;
+
+	/**
+		It a string
+	**/
+	var s:String;
+} #elseif cs(a:String, b:Int) -> Void #elseif neko Array<Int> #else {} #end;

themes/default/resources/styles.css

@@ -126,11 +126,6 @@ footer {
     padding-top: 4px;
 }
 
-/* .availability { margin-left:14px; color:#93a1a1; } */
-/* .doc { margin-left:14px; } */
-
-
-
 /* #nav li { list-style-type: none; } */
 #nav .expando>ul {
     display: none;
@@ -188,6 +183,10 @@ footer {
     font-size: 90%;
 }
 
+.section-availability {
+    color: #e48931;
+}
+
 h3 code {
     background: none;
     box-shadow: 0 0 15px rgb(240, 240, 240);

themes/default/templates/abstract.mtt

@@ -3,17 +3,17 @@
 		<span ::cond api.hasSourceLink(type):: class="viewsource">
 			<a href="::api.getSourceLink(type)::" class="btn btn-medium"><i class="fa fa-eye"></i> View source</a>
 		</span>
-		<h1><small>::if api.isEnumAbstract(type)::enum ::end::abstract</small> ::api.getPathName(type.path)::$$printTypeParams(::type.params::)::if !api.isCoreType(type)::($$printLinkedType(::type.athis::))::end::</h1>
+		<h1><small>::if api.isEnumAbstract(type)::enum ::end::abstract</small> ::api.getPathName(type.path)::$$printTypeParams(::type.params::)::if !api.isCoreType(type)::($$printLinkedType(::type.athis::,::fales::))::end::</h1>
 		$$printPackage(::type::)
 		<h4 ::cond (type.from != null || type.to != null)::>
 			::foreach t type.from::
 				::if t.field == null::
-				<small>::if(repeat.t.index==0)::from ::end::$$printLinkedType(::t.t::)::if((type.from.length!=1)&&(repeat.t.index<type.from.length-1))::, ::end::</small>
+				<small>::if(repeat.t.index==0)::from ::end::$$printLinkedType(::t.t::,::false::)::if((type.from.length!=1)&&(repeat.t.index<type.from.length-1))::, ::end::</small>
 				::end::
 			::end::
 			::foreach t type.to::
 				::if t.field == null::
-				<small>::if(repeat.t.index==0):: to ::end::$$printLinkedType(::t.t::)::if((type.to.length!=1)&&(repeat.t.index<type.to.length-1))::, ::end::</small>
+				<small>::if(repeat.t.index==0):: to ::end::$$printLinkedType(::t.t::,::false::)::if((type.to.length!=1)&&(repeat.t.index<type.to.length-1))::, ::end::</small>
 				::end::
 			::end::
 		</h4>

themes/default/templates/class.mtt

@@ -14,10 +14,10 @@
 			<small>extends 
 				::if (inheritedFields.types.length>0)::
 					::foreach t inheritedFields.types::
-					$$printLinkedPath(::t.path::,::null::)::if ((inheritedFields.types.length!=1)&&(repeat.t.index<(inheritedFields.types.length-1))):: &rsaquo; ::end::
+					$$printLinkedPath(::t.path::,::null::,::false::)::if ((inheritedFields.types.length!=1)&&(repeat.t.index<(inheritedFields.types.length-1))):: &rsaquo; ::end::
 					::end::
 				::else::
-					$$printLinkedPath(::type.superClass.path::,::null::)
+					$$printLinkedPath(::type.superClass.path::,::null::,::false::)
 				::end::
 			</small>
 		</h4>
@@ -26,7 +26,7 @@
 		<h4 ::cond (type.interfaces.length>0)::>
 		<small>::if type.isInterface::extends::else::implements::end:: 
 		::foreach i type.interfaces::
-			$$printLinkedPath(::i.path::,::i.params::)::if ((type.interfaces.length!=1)&&(repeat.i.index<(type.interfaces.length-1)))::, ::end::
+			$$printLinkedPath(::i.path::,::i.params::,::false::)::if ((type.interfaces.length!=1)&&(repeat.i.index<(type.interfaces.length-1)))::, ::end::
 		::end::
 		</small>
 		</h4>

themes/default/templates/enum_field.mtt

@@ -6,7 +6,7 @@
 				<span class="identifier">::ctor.name::</span>
 			</a>
 			::if ctor.args != null::
-				(::foreach arg ctor.args::::arg.name:::$$printLinkedType(::arg.t::)::if !repeat.arg.last::, ::end::::end::)
+				(::foreach arg ctor.args::::arg.name:::$$printLinkedType(::arg.t::,::false::)::if !repeat.arg.last::, ::end::::end::)
 			::end::
 		</code>
 	</h3>

themes/default/templates/macros.mtt

@@ -24,49 +24,55 @@
 	</p>
 </macro>
 
-<macro name="printLinkedPath(path, params)">
+<macro name="printLinkedPath(path, params, qualified)">
 	::if api.isKnownType(path)::
-		<a class="type" title="::api.getSentenceDesc(api.resolveType(path))::" ::attr href api.pathToUrl(path)::>::api.getPathName(path)::</a>
+		<a class="type" title="::api.getSentenceDesc(api.resolveType(path))::" ::attr href api.pathToUrl(path)::>
+			::if qualified::
+				::path::
+			::else::
+				::api.getPathName(path)::
+			::end::
+		</a>
 	::else::
 		<span class="type">::api.getPathName(path)::</span>
 	::end::
 	::if params != null && params.length > 0::
 		&lt;
 		::foreach param params::
-			$$printLinkedType(::param::)
+			$$printLinkedType(::param::,::qualified::)
 			::if !repeat.param.last::, ::end::
 		::end::
 		&gt;
 	::end::
 </macro>
 
-<macro name="printLinkedType(ctype)">
+<macro name="printLinkedType(ctype, qualified)">
 	::switch ctype::
 	::case::Unknown
-	::case::$$printLinkedPath(::args[0]::,::args[1]::)
-	::case::$$printLinkedPath(::args[0]::,::args[1]::)
-	::case::$$printLinkedPath(::args[0]::,::args[1]::)
+	::case::$$printLinkedPath(::args[0]::,::args[1]::,::qualified::)
+	::case::$$printLinkedPath(::args[0]::,::args[1]::,::qualified::)
+	::case::$$printLinkedPath(::args[0]::,::args[1]::,::qualified::)
 	::case::
 		::if args[0].length != 1 || args[0][0].name != ""::(::end::
 		::foreach arg args[0]::
 			::if arg.name != ""::
 				::arg.name:::
 			::end::
-			$$printLinkedType(::arg.t::)
+			$$printLinkedType(::arg.t::,::qualified::)
 			::if !repeat.arg.last::, ::end::
 		::end::
 		::if args[0].length != 1 || args[0][0].name != ""::)::end::
 		&nbsp;&#8209;&gt;&nbsp;
-		$$printLinkedType(::args[1]::)
+		$$printLinkedType(::args[1]::,::qualified::)
 	::case::
 	{
 		::foreach field args[0]::
-			::field.name:::$$printLinkedType(::field.type::)
+			::field.name:::$$printLinkedType(::field.type::,::qualified::)
 			::if !repeat.field.last::, ::end::
 		::end::
 	}
-	::case::$$printLinkedPath(::"Dynamic"::,::null::)::if args[0] != null::&lt;$$printLinkedType(::args[0]::)&gt;::end::
-	::case::$$printLinkedPath(::args[0]::,::args[1]::)
+	::case::$$printLinkedPath(::"Dynamic"::,::null::,::qualified::)::if args[0] != null::&lt;$$printLinkedType(::args[0]::,::qualified::)&gt;::end::
+	::case::$$printLinkedPath(::args[0]::,::args[1]::,::qualified::)
 	::end::
 </macro>
 
@@ -152,23 +158,23 @@
 			<span class="label">write only</span>
 		::end::
 
-	<a href="#::field.name::"><span class="identifier">::field.name::</span></a>:$$printLinkedType(::field.type::)$$printInitExpr(::field.expr::)
+	<a href="#::field.name::"><span class="identifier">::field.name::</span></a>:$$printLinkedType(::field.type::,::false::)$$printInitExpr(::field.expr::)
 
 	::case 2::
 		<a href="#::field.name::"><span class="identifier">::field.name::</span></a>
 		$$printTypeParams(::field.params::)(
 		::foreach arg args[0]::
 			<span style="white-space:nowrap">
 				::if arg.opt && (arg.value == null || arg.value == "null")::?::end::
-				::arg.name:::$$printLinkedType(::arg.t::)
+				::arg.name:::$$printLinkedType(::arg.t::,::false::)
 				::if arg.value != null && arg.value != "null":: = ::arg.value::::end::
 				::if !repeat.arg.last::,::end::
 			</span>
 			::if !repeat.arg.last:: ::end::
 		::end::
 		)
 		::if field.name != "new"::
-			:$$printLinkedType(::args[1]::)
+			:$$printLinkedType(::args[1]::,::false::)
 		::end::
 	::end::
 	</code>
@@ -283,7 +289,7 @@
 		<div class="fields" ::cond hasFields::>
 			::set fields=inheritedFields.fields::
 			::foreach cl inheritedFields.types::
-				<h4 ::cond fields.get(cl).length>0::><a href="#" class="expand-button"><i class="fa fa-arrow-circle-o-right"></i></a> Defined by $$printLinkedPath(::cl.path::,::null::)</h4>
+				<h4 ::cond fields.get(cl).length>0::><a href="#" class="expand-button"><i class="fa fa-arrow-circle-o-right"></i></a> Defined by $$printLinkedPath(::cl.path::,::null::,::false::)</h4>
 				<div style="display:none">
 				::foreach field fields.get(cl)::
 					::set isStatic = false::
@@ -298,7 +304,7 @@
 		<div class="fields" ::cond hasMethods::>
 			::set fields=inheritedFields.methods::
 			::foreach cl inheritedFields.types::
-				<h4 ::cond fields.get(cl).length>0::><a href="#" class="expand-button"><i class="fa fa-arrow-circle-o-right"></i></a> Defined by $$printLinkedPath(::cl.path::,::null::)</h4>
+				<h4 ::cond fields.get(cl).length>0::><a href="#" class="expand-button"><i class="fa fa-arrow-circle-o-right"></i></a> Defined by $$printLinkedPath(::cl.path::,::null::,::false::)</h4>
 				<div style="display:none">
 				::foreach field fields.get(cl)::
 				::set isStatic = false::

themes/default/templates/related_types.mtt

@@ -1,4 +1,4 @@
 <span class="muted">::title::</span>
 ::foreach info infos::
-	$$printLinkedPath(::info.path::,::null::)::if !repeat.info.last::, ::end::
+	$$printLinkedPath(::info.path::,::null::,::false::)::if !repeat.info.last::, ::end::
 ::end::

themes/default/templates/typedef.mtt

@@ -5,14 +5,6 @@
 		</span>
 		<h1><small>typedef</small> ::api.getPathName(type.path)::$$printTypeParams(::type.params::)</h1>
 		$$printPackage(::type::)
-
-		::switch type.type::
-		<h4>
-			<small>alias for $$printLinkedType(::type.type::)</small>
-		</h4>
-		::case 5::
-		::end::
-
 		$$printModule(::type.module::)
 		$$printMeta(::type::)
 		$$printDeprecation(::type::)
@@ -24,23 +16,32 @@
 			::raw type.doc::
 		</div>
 
-		::set showSection = false::
-		::switch type.type::
-		::case 5::
-			::foreach field args[0]::
-				::eval showSection = true::
+		::set multiplePlatforms = api.lambda.array(type.types).length > 1::
+		::foreach platform type.types.keys()::
+			::set platformType = type.types.get(platform)::
+			::if multiplePlatforms::
+				<h4 class="section section-availability">::platform::</h4>
 			::end::
-		::end::
-		::if showSection::
-			<h3 class="section">Properties</h3>
-			<div class="fields">
-				::switch type.type::
-				::case 5::
-					::foreach field args[0]::
-						::use "class_field.mtt"::::end::
+			::switch platformType::
+				<div class="fields">
+					<div class="field">
+						<em>alias for </em><code>$$printLinkedType(::platformType::,::true::)</code>
+					</div>
+				</div>
+			::case 5::
+				<div class="fields">
+					::switch platformType::
+					::case 5::
+						::if args[0].length == 0::
+							<em>empty structure</em>
+						::else::
+							::foreach field args[0]::
+								::use "class_field.mtt"::::end::
+							::end::
+						::end::
 					::end::
-				::end::
-			</div>
+				</div>
+			::end::
 		::end::
 	</div>
 ::end::

xml.hxml

@@ -4,7 +4,6 @@ dox
 -D doc-gen
 
 --each
-
 -cpp all_cpp
 -xml bin/xml/cpp.xml
 -D HXCPP_MULTI_THREADED
@@ -17,3 +16,7 @@ dox
 -cs all_cs
 -D unsafe
 -xml bin/xml/cs.xml
+
+--next
+-neko all_neko
+-xml bin/xml/neko.xml