Commit 1db99b08e29dd4c8e3dbb8d91e7f0139ec75a008 | zig

author	Loris Cro <kappaloris@gmail.com> 2022-08-08 18:31:01+02:00
committer	GitHub <noreply@github.com> 2022-08-08 18:31:01+02:00
log	1db99b08e29dd4c8e3dbb8d91e7f0139ec75a008
tree	9514f00311fe7a19bea12035244927c55df4ec07
parent	396eb730e5133c150134bb675ee43d5323e2bb6d
parent	ff6d2e632f8191ae7cbb048770ef2ecff00f72c7
signature	Signed by PGP key 4AEE18F83AFDEB23

Merge pull request #12347 from r00ster91/nicedocs

autodoc: various improvements

2 files changed, 138 insertions(+), 117 deletions(-)

lib
- docs
  - index.html
  - main.js

lib/docs/index.html+66-63

...	...	@@ -25,9 +25,10 @@
25	25	--search-bg-color-focus: #ffffff;
26	26	--search-sh-color: rgba(0, 0, 0, 0.18);
27	27	--help-sh-color: rgba(0, 0, 0, 0.75);
	28	--help-bg-color: #aaa;
28	29	}
29	30
30		html, body { margin: 0; padding:0; height: 100%; }
	31	html, body { margin: 0; padding: 0; height: 100%; }
31	32
32	33	a {
33	34	text-decoration: none;
...	...	@@ -190,11 +191,11 @@
190	191	box-shadow: 0 0.3em 1em 0.125em var(--search-sh-color);
191	192	}
192	193
193		.docs .search::placeholder {
194		font-size: 1rem;
195		font-family: var(--ui);
196		color: var(--tx-color);
197		opacity: 0.5;
	194	#searchPlaceholder {
	195	position: absolute;
	196	pointer-events: none;
	197	top: 5px;
	198	left: 5px;
198	199	}
199	200
200	201	.docs a {
...	...	@@ -207,9 +208,9 @@
207	208
208	209	.docs pre {
209	210	font-family: var(--mono);
210		font-size:1em;
211		background-color:#F5F5F5;
212		padding:1em;
	211	font-size: 1em;
	212	background-color: #F5F5F5;
	213	padding: 1em;
213	214	overflow-x: auto;
214	215	}
215	216
...	...	@@ -225,7 +226,7 @@
225	226	border-bottom: 0.0625rem dashed;
226	227	}
227	228
228		.docs h2 {
	229	.docs h2 {
229	230	font-size: 1.3em;
230	231	margin: 0.5em 0;
231	232	padding: 0;
...	...	@@ -294,7 +295,7 @@
294	295	padding: 1px 1em;
295	296	}
296	297
297		/* help dialog */
	298	/* help modal */
298	299	.help-modal {
299	300	display: flex;
300	301	width: 100%;
...	...	@@ -308,13 +309,13 @@
308	309	backdrop-filter: blur(0.3em);
309	310	}
310	311
311		.help-modal > .dialog {
	312	.help-modal > .modal {
312	313	max-width: 97vw;
313	314	max-height: 97vh;
314	315	overflow: auto;
315	316	font-size: 1rem;
316	317	color: #fff;
317		background-color: #333;
	318	background-color: var(--help-bg-color);
318	319	border: 0.125rem solid #000;
319	320	box-shadow: 0 0.5rem 2.5rem 0.3rem var(--help-sh-color);
320	321	}
...	...	@@ -335,7 +336,7 @@
335	336	margin-right: 0.5em;
336	337	}
337	338
338		.help-modal kbd {
	339	kbd {
339	340	display: inline-block;
340	341	padding: 0.3em 0.2em;
341	342	font-size: 1.2em;
...	...	@@ -348,16 +349,16 @@
348	349	border-bottom-color: #c6cbd1;
349	350	border: solid 0.0625em;
350	351	border-radius: 0.1875em;
351		box-shadow: inset 0 -0.0625em 0 #c6cbd1;
	352	box-shadow: inset 0 -0.2em 0 #c6cbd1;
352	353	cursor: default;
353	354	}
354	355
355		#listFns dt {
356		font-family: var(--mono);
357		}
358		.argBreaker {
359		display: none;
360		}
	356	#listFns dt {
	357	font-family: var(--mono);
	358	}
	359	.argBreaker {
	360	display: none;
	361	}
361	362
362	363	/* tokens */
363	364	.tok-kw {
...	...	@@ -391,7 +392,6 @@
391	392
392	393	/* dark mode */
393	394	@media (prefers-color-scheme: dark) {
394
395	395	:root {
396	396	--tx-color: #bbb;
397	397	--bg-color: #111;
...	...	@@ -408,6 +408,7 @@
408	408	--search-bg-color-focus: #000;
409	409	--search-sh-color: rgba(255, 255, 255, 0.28);
410	410	--help-sh-color: rgba(142, 142, 142, 0.5);
	411	--help-bg-color: #333;
411	412	}
412	413
413	414	.docs pre {
...	...	@@ -457,7 +458,6 @@
457	458	.tok-type {
458	459	color: #68f;
459	460	}
460
461	461	}
462	462
463	463	@media only screen and (max-width: 750px) {
...	...	@@ -544,7 +544,7 @@
544	544	<body class="canvas">
545	545	<div class="banner">
546	546	This is a beta autodoc build; expect bugs and missing information.
547		<a href="https://github.com/ziglang/zig/wiki/How-to-contribute-to-Autodoc">Report an Issue</a>,
	547	<a href="https://github.com/ziglang/zig/wiki/How-to-contribute-to-Autodoc">Report an Issue</a>,
548	548	<a href="https://github.com/ziglang/zig/wiki/How-to-contribute-to-Autodoc">Contribute</a>,
549	549	<a href="https://github.com/ziglang/zig/wiki/How-to-read-the-standard-library-source-code">Learn more about stdlib source code</a>.
550	550	</div>
...	...	@@ -555,43 +555,43 @@
555	555	<div class="logo">
556	556	<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 140">
557	557	<g fill="#F7A41D">
558		<g>
559		<polygon points="46,22 28,44 19,30"/>
560		<polygon points="46,22 33,33 28,44 22,44 22,95 31,95 20,100 12,117 0,117 0,22" shape-rendering="crispEdges"/>
561		<polygon points="31,95 12,117 4,106"/>
562		</g>
563		<g>
564		<polygon points="56,22 62,36 37,44"/>
565		<polygon points="56,22 111,22 111,44 37,44 56,32" shape-rendering="crispEdges"/>
566		<polygon points="116,95 97,117 90,104"/>
567		<polygon points="116,95 100,104 97,117 42,117 42,95" shape-rendering="crispEdges"/>
568		<polygon points="150,0 52,117 3,140 101,22"/>
569		</g>
570		<g>
571		<polygon points="141,22 140,40 122,45"/>
572		<polygon points="153,22 153,117 106,117 120,105 125,95 131,95 131,45 122,45 132,36 141,22" shape-rendering="crispEdges"/>
573		<polygon points="125,95 130,110 106,117"/>
574		</g>
	558	<g>
	559	<polygon points="46,22 28,44 19,30"/>
	560	<polygon points="46,22 33,33 28,44 22,44 22,95 31,95 20,100 12,117 0,117 0,22" shape-rendering="crispEdges"/>
	561	<polygon points="31,95 12,117 4,106"/>
	562	</g>
	563	<g>
	564	<polygon points="56,22 62,36 37,44"/>
	565	<polygon points="56,22 111,22 111,44 37,44 56,32" shape-rendering="crispEdges"/>
	566	<polygon points="116,95 97,117 90,104"/>
	567	<polygon points="116,95 100,104 97,117 42,117 42,95" shape-rendering="crispEdges"/>
	568	<polygon points="150,0 52,117 3,140 101,22"/>
	569	</g>
	570	<g>
	571	<polygon points="141,22 140,40 122,45"/>
	572	<polygon points="153,22 153,117 106,117 120,105 125,95 131,95 131,45 122,45 132,36 141,22" shape-rendering="crispEdges"/>
	573	<polygon points="125,95 130,110 106,117"/>
	574	</g>
575	575	</g>
576	576	<style>
577	577	#text { fill: #121212 }
578	578	@media (prefers-color-scheme: dark) { #text { fill: #f2f2f2 } }
579	579	</style>
580	580	<g id="text">
581		<g>
582		<polygon points="260,22 260,37 229,40 177,40 177,22" shape-rendering="crispEdges"/>
583		<polygon points="260,37 207,99 207,103 176,103 229,40 229,37"/>
584		<polygon points="261,99 261,117 176,117 176,103 206,99" shape-rendering="crispEdges"/>
585		</g>
586		<rect x="272" y="22" shape-rendering="crispEdges" width="22" height="95"/>
587		<g>
588		<polygon points="394,67 394,106 376,106 376,81 360,70 346,67" shape-rendering="crispEdges"/>
589		<polygon points="360,68 376,81 346,67"/>
590		<path d="M394,106c-10.2,7.3-24,12-37.7,12c-29,0-51.1-20.8-51.1-48.3c0-27.3,22.5-48.1,52-48.1 c14.3,0,29.2,5.5,38.9,14l-13,15c-7.1-6.3-16.8-10-25.9-10c-17,0-30.2,12.9-30.2,29.5c0,16.8,13.3,29.6,30.3,29.6 c5.7,0,12.8-2.3,19-5.5L394,106z"/>
591		</g>
	581	<g>
	582	<polygon points="260,22 260,37 229,40 177,40 177,22" shape-rendering="crispEdges"/>
	583	<polygon points="260,37 207,99 207,103 176,103 229,40 229,37"/>
	584	<polygon points="261,99 261,117 176,117 176,103 206,99" shape-rendering="crispEdges"/>
	585	</g>
	586	<rect x="272" y="22" shape-rendering="crispEdges" width="22" height="95"/>
	587	<g>
	588	<polygon points="394,67 394,106 376,106 376,81 360,70 346,67" shape-rendering="crispEdges"/>
	589	<polygon points="360,68 376,81 346,67"/>
	590	<path d="M394,106c-10.2,7.3-24,12-37.7,12c-29,0-51.1-20.8-51.1-48.3c0-27.3,22.5-48.1,52-48.1 c14.3,0,29.2,5.5,38.9,14l-13,15c-7.1-6.3-16.8-10-25.9-10c-17,0-30.2,12.9-30.2,29.5c0,16.8,13.3,29.6,30.3,29.6 c5.7,0,12.8-2.3,19-5.5L394,106z"/>
	591	</g>
592	592	</g>
593	593	</svg>
594		</div>
	594	</div>
595	595	<div id="sectMainPkg" class="hidden">
596	596	<h2><span>Main Package</span></h2>
597	597	<ul class="packages">
...	...	@@ -606,16 +606,19 @@
606	606	<h2><span>Zig Version</span></h2>
607	607	<p class="str" id="tdZigVer"></p>
608	608	</div>
609		<div>
610		<input id="privDeclsBox" type="checkbox"/>
611		<label for="privDeclsBox">Internal Doc Mode</label>
612		</div>
	609	<div>
	610	<input id="privDeclsBox" type="checkbox"/>
	611	<label for="privDeclsBox">Internal Doc Mode</label>
	612	</div>
613	613	</nav>
614	614	</div>
615	615	<div class="flex-right">
616	616	<div class="wrap">
617	617	<section class="docs">
618		<input type="search" class="search" id="search" autocomplete="off" spellcheck="false" placeholder="`s` to search, `?` to see more options">
	618	<div style="position: relative">
	619	<span id="searchPlaceholder"><kbd>S</kbd> to search, <kbd>?</kbd> for more options</span>
	620	<input type="search" class="search" id="search" autocomplete="off" spellcheck="false" disabled>
	621	</div>
619	622	<p id="status">Loading...</p>
620	623	<div id="sectNav" class="hidden"><ul id="listNav"></ul></div>
621	624	<div id="fnProto" class="hidden">
...	...	@@ -703,17 +706,17 @@
703	706	</table>
704	707	</div>
705	708	</div>
706		</section>
	709	</section>
707	710	</div>
708	711	<div class="flex-filler"></div>
709	712	</div>
710	713	</div>
711		<div id="helpDialog" class="hidden">
	714	<div id="helpModal" class="hidden">
712	715	<div class="help-modal">
713		<div class="dialog">
	716	<div class="modal">
714	717	<h1>Keyboard Shortcuts</h1>
715		<dl><dt><kbd>?</kbd></dt><dd>Show this help dialog</dd></dl>
716		<dl><dt><kbd>Esc</kbd></dt><dd>Clear focus; close this dialog</dd></dl>
	718	<dl><dt><kbd>?</kbd></dt><dd>Show this help modal</dd></dl>
	719	<dl><dt><kbd>Esc</kbd></dt><dd>Clear focus; close this modal</dd></dl>
717	720	<dl><dt><kbd>s</kbd></dt><dd>Focus the search field</dd></dl>
718	721	<dl><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd></dl>
719	722	<dl><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd></dl>

lib/docs/main.js+72-54

...	...	@@ -3,53 +3,54 @@
3	3	var zigAnalysis;
4	4
5	5	(function () {
6		let domStatus = document.getElementById("status");
7		let domSectNav = document.getElementById("sectNav");
8		let domListNav = document.getElementById("listNav");
9		let domSectMainPkg = document.getElementById("sectMainPkg");
10		let domSectPkgs = document.getElementById("sectPkgs");
11		let domListPkgs = document.getElementById("listPkgs");
12		let domSectTypes = document.getElementById("sectTypes");
13		let domListTypes = document.getElementById("listTypes");
14		let domSectTests = document.getElementById("sectTests");
15		let domListTests = document.getElementById("listTests");
16		let domSectNamespaces = document.getElementById("sectNamespaces");
17		let domListNamespaces = document.getElementById("listNamespaces");
18		let domSectErrSets = document.getElementById("sectErrSets");
19		let domListErrSets = document.getElementById("listErrSets");
20		let domSectFns = document.getElementById("sectFns");
21		let domListFns = document.getElementById("listFns");
22		let domSectFields = document.getElementById("sectFields");
23		let domListFields = document.getElementById("listFields");
24		let domSectGlobalVars = document.getElementById("sectGlobalVars");
25		let domListGlobalVars = document.getElementById("listGlobalVars");
26		let domSectValues = document.getElementById("sectValues");
27		let domListValues = document.getElementById("listValues");
28		let domFnProto = document.getElementById("fnProto");
29		let domFnProtoCode = document.getElementById("fnProtoCode");
30		let domSectParams = document.getElementById("sectParams");
31		let domListParams = document.getElementById("listParams");
32		let domTldDocs = document.getElementById("tldDocs");
33		let domSectFnErrors = document.getElementById("sectFnErrors");
34		let domListFnErrors = document.getElementById("listFnErrors");
35		let domTableFnErrors = document.getElementById("tableFnErrors");
36		let domFnErrorsAnyError = document.getElementById("fnErrorsAnyError");
37		let domFnExamples = document.getElementById("fnExamples");
38		// let domListFnExamples = (document.getElementById("listFnExamples"));
39		let domFnNoExamples = document.getElementById("fnNoExamples");
40		let domDeclNoRef = document.getElementById("declNoRef");
41		let domSearch = document.getElementById("search");
42		let domSectSearchResults = document.getElementById("sectSearchResults");
43		let domSectSearchAllResultsLink = document.getElementById("sectSearchAllResultsLink");
44
45		let domListSearchResults = document.getElementById("listSearchResults");
46		let domSectSearchNoResults = document.getElementById("sectSearchNoResults");
47		let domSectInfo = document.getElementById("sectInfo");
48		// let domTdTarget = (document.getElementById("tdTarget"));
49		let domPrivDeclsBox = document.getElementById("privDeclsBox");
50		let domTdZigVer = document.getElementById("tdZigVer");
51		let domHdrName = document.getElementById("hdrName");
52		let domHelpModal = document.getElementById("helpDialog");
	6	const domStatus = document.getElementById("status");
	7	const domSectNav = document.getElementById("sectNav");
	8	const domListNav = document.getElementById("listNav");
	9	const domSectMainPkg = document.getElementById("sectMainPkg");
	10	const domSectPkgs = document.getElementById("sectPkgs");
	11	const domListPkgs = document.getElementById("listPkgs");
	12	const domSectTypes = document.getElementById("sectTypes");
	13	const domListTypes = document.getElementById("listTypes");
	14	const domSectTests = document.getElementById("sectTests");
	15	const domListTests = document.getElementById("listTests");
	16	const domSectNamespaces = document.getElementById("sectNamespaces");
	17	const domListNamespaces = document.getElementById("listNamespaces");
	18	const domSectErrSets = document.getElementById("sectErrSets");
	19	const domListErrSets = document.getElementById("listErrSets");
	20	const domSectFns = document.getElementById("sectFns");
	21	const domListFns = document.getElementById("listFns");
	22	const domSectFields = document.getElementById("sectFields");
	23	const domListFields = document.getElementById("listFields");
	24	const domSectGlobalVars = document.getElementById("sectGlobalVars");
	25	const domListGlobalVars = document.getElementById("listGlobalVars");
	26	const domSectValues = document.getElementById("sectValues");
	27	const domListValues = document.getElementById("listValues");
	28	const domFnProto = document.getElementById("fnProto");
	29	const domFnProtoCode = document.getElementById("fnProtoCode");
	30	const domSectParams = document.getElementById("sectParams");
	31	const domListParams = document.getElementById("listParams");
	32	const domTldDocs = document.getElementById("tldDocs");
	33	const domSectFnErrors = document.getElementById("sectFnErrors");
	34	const domListFnErrors = document.getElementById("listFnErrors");
	35	const domTableFnErrors = document.getElementById("tableFnErrors");
	36	const domFnErrorsAnyError = document.getElementById("fnErrorsAnyError");
	37	const domFnExamples = document.getElementById("fnExamples");
	38	// const domListFnExamples = (document.getElementById("listFnExamples"));
	39	const domFnNoExamples = document.getElementById("fnNoExamples");
	40	const domDeclNoRef = document.getElementById("declNoRef");
	41	const domSearch = document.getElementById("search");
	42	const domSectSearchResults = document.getElementById("sectSearchResults");
	43	const domSectSearchAllResultsLink = document.getElementById("sectSearchAllResultsLink");
	44
	45	const domListSearchResults = document.getElementById("listSearchResults");
	46	const domSectSearchNoResults = document.getElementById("sectSearchNoResults");
	47	const domSectInfo = document.getElementById("sectInfo");
	48	// const domTdTarget = (document.getElementById("tdTarget"));
	49	const domPrivDeclsBox = document.getElementById("privDeclsBox");
	50	const domTdZigVer = document.getElementById("tdZigVer");
	51	const domHdrName = document.getElementById("hdrName");
	52	const domHelpModal = document.getElementById("helpModal");
	53	const domSearchPlaceholder = document.getElementById("searchPlaceholder");
53	54
54	55	let searchTimer = null;
55	56	let searchTrimResults = true;
...	...	@@ -104,7 +105,15 @@ var zigAnalysis;
104	105	// map of decl index to list of comptime fn calls
105	106	// let nodesToCallsMap = indexNodesToCalls();
106	107
	108	domSearch.disabled = false;
107	109	domSearch.addEventListener("keydown", onSearchKeyDown, false);
	110	domSearch.addEventListener("focus", ev => {
	111	domSearchPlaceholder.classList.add("hidden");
	112	});
	113	domSearch.addEventListener("blur", ev => {
	114	if (domSearch.value.length == 0)
	115	domSearchPlaceholder.classList.remove("hidden");
	116	});
108	117	domSectSearchAllResultsLink.addEventListener('click', onClickSearchShowAllResults, false);
109	118	function onClickSearchShowAllResults(ev) {
110	119	ev.preventDefault();
...	...	@@ -112,7 +121,7 @@ var zigAnalysis;
112	121	searchTrimResults = false;
113	122	onHashChange();
114	123	}
115
	124
116	125	domPrivDeclsBox.addEventListener(
117	126	"change",
118	127	function () {
...	...	@@ -142,6 +151,12 @@ var zigAnalysis;
142	151	location.hash = "#root";
143	152	}
144	153
	154	// make the modal disappear if you click outside it
	155	domHelpModal.addEventListener("click", ev => {
	156	if (ev.target.className == "help-modal")
	157	domHelpModal.classList.add("hidden");
	158	});
	159
145	160	window.addEventListener("hashchange", onHashChange, false);
146	161	window.addEventListener("keydown", onWindowKeyDown, false);
147	162	onHashChange();
...	...	@@ -2628,6 +2643,10 @@ var zigAnalysis;
2628	2643	updateCurNav();
2629	2644	if (domSearch.value !== curNavSearch) {
2630	2645	domSearch.value = curNavSearch;
	2646	if (domSearch.value.length == 0)
	2647	domSearchPlaceholder.classList.remove("hidden");
	2648	else
	2649	domSearchPlaceholder.classList.add("hidden");
2631	2650	}
2632	2651	render();
2633	2652	if (imFeelingLucky) {
...	...	@@ -2749,7 +2768,7 @@ var zigAnalysis;
2749	2768	});
2750	2769	}
2751	2770
2752		// Generic fun/ction
	2771	// Generic function
2753	2772	if (value.kind == typeKinds.Fn && value.generic_ret != null) {
2754	2773	let resolvedVal = resolveValue({ expr: value.generic_ret });
2755	2774	if ("type" in resolvedVal.expr) {
...	...	@@ -3343,12 +3362,11 @@ var zigAnalysis;
3343	3362	return operatorCompare(a.decl.name, b.decl.name);
3344	3363	});
3345	3364
3346
3347		var searchTrimmed = false
3348		var searchTrimResultsMaxItems = 200
	3365	let searchTrimmed = false;
	3366	const searchTrimResultsMaxItems = 200;
3349	3367	if (searchTrimResults && matchedItems.length > searchTrimResultsMaxItems) {
3350		matchedItems = matchedItems.slice(0, searchTrimResultsMaxItems)
3351		searchTrimmed = true
	3368	matchedItems = matchedItems.slice(0, searchTrimResultsMaxItems);
	3369	searchTrimmed = true;
3352	3370	}
3353	3371
3354	3372	// Build up the list of search results