Skip to content

Commit 6a98054

Browse files
panglesdpanglesd
committed
Span labels in function arguments (?id: and id:)
Signed-off-by: Paul-Elliot <[email protected]>
1 parent ae44182 commit 6a98054

15 files changed

+66
-41
lines changed

‎src/document/generator.ml

+4-4
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,12 @@ open Types
2121
module O = Codefmt
2222
open O.Infix
2323

24+
let tag tag t = O.span ~attr:tag t
25+
2426
let label t =
2527
match t with
26-
| Odoc_model.Lang.TypeExpr.Label s -> O.txt s
27-
| Optional s -> O.txt "?" ++ O.txt s
28-
29-
let tag tag t = O.span ~attr:tag t
28+
| Odoc_model.Lang.TypeExpr.Label s -> tag "label" (O.txt s)
29+
| Optional s -> tag "optlabel" (O.txt "?" ++ O.txt s)
3030

3131
let type_var tv = tag "type-var" (O.txt tv)
3232

‎src/html_support_files/odoc.css

+9
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,7 @@
119119
--toc-list-border: #ccc;
120120

121121
--spec-summary-border-color: #5c9cf5;
122+
--spec-label-color: green;
122123
--spec-summary-background: var(--code-background);
123124
--spec-summary-hover-background: #ebeff2;
124125
--spec-details-after-background: rgba(0, 4, 15, 0.05);
@@ -158,6 +159,8 @@
158159
--hljs-type: #ac885b;
159160
--hljs-meta: #82aaff;
160161
--hljs-variable: #cf6a4c;
162+
163+
--spec-label-color: lightgreen;
161164
}
162165

163166
@media (prefers-color-scheme: dark) {
@@ -204,6 +207,8 @@
204207
--hljs-type: #ac885b;
205208
--hljs-meta: #82aaff;
206209
--hljs-variable: #cf6a4c;
210+
211+
--spec-label-color: lightgreen;
207212
}
208213
}
209214

@@ -525,6 +530,10 @@ p a > code, li a > code {
525530
padding: 0.35em 0.5em;
526531
}
527532

533+
.spec .label, .spec .optlabel {
534+
color: var(--spec-label-color);
535+
}
536+
528537
li:not(:last-child) > .def-doc {
529538
margin-bottom: 15px;
530539
}

‎src/html_support_files/odoc_html_support_files.ml

+12-12
Large diffs are not rendered by default.

‎test/generators/html/Bugs.html

+2-2
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@ <h1>Module <code><span>Bugs</span></code></h1>
2424
<a href="#val-foo" class="anchor"></a>
2525
<code>
2626
<span><span class="keyword">val</span> foo :
27-
<span>?bar:<span class="type-var">'a</span>
28-
<span class="arrow">&#45;&gt;</span>
27+
<span><span class="optlabel">?bar</span>:
28+
<span class="type-var">'a</span> <span class="arrow">&#45;&gt;</span>
2929
</span> <span>unit <span class="arrow">&#45;&gt;</span></span>
3030
unit
3131
</span>

‎test/generators/html/Bugs_pre_410.html

+2-2
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@ <h1>Module <code><span>Bugs_pre_410</span></code></h1>
2626
<a href="#val-foo'" class="anchor"></a>
2727
<code>
2828
<span><span class="keyword">val</span> foo' :
29-
<span>?bar:<span class="type-var">'a</span>
30-
<span class="arrow">&#45;&gt;</span>
29+
<span><span class="optlabel">?bar</span>:
30+
<span class="type-var">'a</span> <span class="arrow">&#45;&gt;</span>
3131
</span> <span>unit <span class="arrow">&#45;&gt;</span></span>
3232
unit
3333
</span>

‎test/generators/html/Ocamlary.html

+7-3
Original file line numberDiff line numberDiff line change
@@ -388,7 +388,9 @@ <h4 id="basic-type-and-value-stuff-with-advanced-doc-comments">
388388
<a href="#val-a_function" class="anchor"></a>
389389
<code>
390390
<span><span class="keyword">val</span> a_function :
391-
<span>x:int <span class="arrow">&#45;&gt;</span></span> int
391+
<span><span class="label">x</span>:int
392+
<span class="arrow">&#45;&gt;</span>
393+
</span> int
392394
</span>
393395
</code>
394396
</div>
@@ -430,8 +432,10 @@ <h4 id="basic-type-and-value-stuff-with-advanced-doc-comments">
430432
<a href="#val-fun_maybe" class="anchor"></a>
431433
<code>
432434
<span><span class="keyword">val</span> fun_maybe :
433-
<span>?yes:unit <span class="arrow">&#45;&gt;</span></span>
434-
<span>unit <span class="arrow">&#45;&gt;</span></span> int
435+
<span><span class="optlabel">?yes</span>:unit
436+
<span class="arrow">&#45;&gt;</span>
437+
</span> <span>unit <span class="arrow">&#45;&gt;</span></span>
438+
int
435439
</span>
436440
</code>
437441
</div>

‎test/generators/html/Type.html

+16-4
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,10 @@ <h1>Module <code><span>Type</span></code></h1>
6868
<div class="spec type anchored" id="type-labeled">
6969
<a href="#type-labeled" class="anchor"></a>
7070
<code><span><span class="keyword">type</span> labeled</span>
71-
<span> = <span>l:int <span class="arrow">&#45;&gt;</span></span> int
71+
<span> =
72+
<span><span class="label">l</span>:int
73+
<span class="arrow">&#45;&gt;</span>
74+
</span> int
7275
</span>
7376
</code>
7477
</div>
@@ -77,7 +80,10 @@ <h1>Module <code><span>Type</span></code></h1>
7780
<div class="spec type anchored" id="type-optional">
7881
<a href="#type-optional" class="anchor"></a>
7982
<code><span><span class="keyword">type</span> optional</span>
80-
<span> = <span>?l:int <span class="arrow">&#45;&gt;</span></span> int
83+
<span> =
84+
<span><span class="optlabel">?l</span>:int
85+
<span class="arrow">&#45;&gt;</span>
86+
</span> int
8187
</span>
8288
</code>
8389
</div>
@@ -89,11 +95,17 @@ <h1>Module <code><span>Type</span></code></h1>
8995
<span><span class="keyword">type</span> labeled_higher_order</span>
9096
<span> =
9197
<span>
92-
<span>(<span>l:int <span class="arrow">&#45;&gt;</span></span> int)
98+
<span>(
99+
<span><span class="label">l</span>:int
100+
<span class="arrow">&#45;&gt;</span>
101+
</span> int)
93102
</span> <span class="arrow">&#45;&gt;</span>
94103
</span>
95104
<span>
96-
<span>(<span>?l:int <span class="arrow">&#45;&gt;</span></span> int)
105+
<span>(
106+
<span><span class="optlabel">?l</span>:int
107+
<span class="arrow">&#45;&gt;</span>
108+
</span> int)
97109
</span> <span class="arrow">&#45;&gt;</span>
98110
</span> int
99111
</span>

‎test/generators/latex/Bugs.tex

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
\section{Module \ocamlinlinecode{Bugs}}\label{module-Bugs}%
22
\label{module-Bugs-type-opt}\ocamlcodefragment{\ocamltag{keyword}{type} 'a opt = \ocamltag{type-var}{'a} option}\\
3-
\label{module-Bugs-val-foo}\ocamlcodefragment{\ocamltag{keyword}{val} foo : ?bar:\ocamltag{type-var}{'a} \ocamltag{arrow}{$\rightarrow$} unit \ocamltag{arrow}{$\rightarrow$} unit}\begin{ocamlindent}Triggers an assertion failure when \href{https://github.com/ocaml/odoc/issues/101}{https://github.com/ocaml/odoc/issues/101}\footnote{\url{https://github.com/ocaml/odoc/issues/101}} is not fixed.\end{ocamlindent}%
3+
\label{module-Bugs-val-foo}\ocamlcodefragment{\ocamltag{keyword}{val} foo : \ocamltag{optlabel}{?bar}:\ocamltag{type-var}{'a} \ocamltag{arrow}{$\rightarrow$} unit \ocamltag{arrow}{$\rightarrow$} unit}\begin{ocamlindent}Triggers an assertion failure when \href{https://github.com/ocaml/odoc/issues/101}{https://github.com/ocaml/odoc/issues/101}\footnote{\url{https://github.com/ocaml/odoc/issues/101}} is not fixed.\end{ocamlindent}%
44
\medbreak
55

66

‎test/generators/latex/Bugs_pre_410.tex

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
\section{Module \ocamlinlinecode{Bugs\_\allowbreak{}pre\_\allowbreak{}410}}\label{module-Bugs_pre_410}%
22
\label{module-Bugs_pre_410-type-opt'}\ocamlcodefragment{\ocamltag{keyword}{type} 'a opt' = int option}\\
3-
\label{module-Bugs_pre_410-val-foo'}\ocamlcodefragment{\ocamltag{keyword}{val} foo' : ?bar:\ocamltag{type-var}{'a} \ocamltag{arrow}{$\rightarrow$} unit \ocamltag{arrow}{$\rightarrow$} unit}\begin{ocamlindent}Similar to \ocamlinlinecode{Bugs}, but the printed type of \ocamlinlinecode{\textasciitilde{}bar} should be \ocamlinlinecode{int}, not \ocamlinlinecode{'a}. This probably requires fixing in the compiler. See \href{https://github.com/ocaml/odoc/pull/230\#issuecomment-433226807}{https://github.com/ocaml/odoc/pull/230\#issuecomment-433226807}\footnote{\url{https://github.com/ocaml/odoc/pull/230\#issuecomment-433226807}}.\end{ocamlindent}%
3+
\label{module-Bugs_pre_410-val-foo'}\ocamlcodefragment{\ocamltag{keyword}{val} foo' : \ocamltag{optlabel}{?bar}:\ocamltag{type-var}{'a} \ocamltag{arrow}{$\rightarrow$} unit \ocamltag{arrow}{$\rightarrow$} unit}\begin{ocamlindent}Similar to \ocamlinlinecode{Bugs}, but the printed type of \ocamlinlinecode{\textasciitilde{}bar} should be \ocamlinlinecode{int}, not \ocamlinlinecode{'a}. This probably requires fixing in the compiler. See \href{https://github.com/ocaml/odoc/pull/230\#issuecomment-433226807}{https://github.com/ocaml/odoc/pull/230\#issuecomment-433226807}\footnote{\url{https://github.com/ocaml/odoc/pull/230\#issuecomment-433226807}}.\end{ocamlindent}%
44
\medbreak
55

66

‎test/generators/latex/Ocamlary.tex

+2-2
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ \subsubsection{Basic exception stuff\label{basic-exception-stuff}}%
135135
\subsubsection{Basic type and value stuff with advanced doc comments\label{basic-type-and-value-stuff-with-advanced-doc-comments}}%
136136
\label{module-Ocamlary-type-a_function}\ocamlcodefragment{\ocamltag{keyword}{type} ('a,\allowbreak{} 'b) a\_\allowbreak{}function = \ocamltag{type-var}{'a} \ocamltag{arrow}{$\rightarrow$} \ocamltag{type-var}{'b}}\begin{ocamlindent}\hyperref[module-Ocamlary-type-a_function]{\ocamlinlinecode{\ocamlinlinecode{a\_\allowbreak{}function}}[p\pageref*{module-Ocamlary-type-a_function}]} is this type and \hyperref[module-Ocamlary-val-a_function]{\ocamlinlinecode{\ocamlinlinecode{a\_\allowbreak{}function}}[p\pageref*{module-Ocamlary-val-a_function}]} is the value below.\end{ocamlindent}%
137137
\medbreak
138-
\label{module-Ocamlary-val-a_function}\ocamlcodefragment{\ocamltag{keyword}{val} a\_\allowbreak{}function : x:int \ocamltag{arrow}{$\rightarrow$} int}\begin{ocamlindent}This is \ocamlinlinecode{a\_\allowbreak{}function} with param and return type.\begin{description}\kern-\topsep
138+
\label{module-Ocamlary-val-a_function}\ocamlcodefragment{\ocamltag{keyword}{val} a\_\allowbreak{}function : \ocamltag{label}{x}:int \ocamltag{arrow}{$\rightarrow$} int}\begin{ocamlindent}This is \ocamlinlinecode{a\_\allowbreak{}function} with param and return type.\begin{description}\kern-\topsep
139139
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
140140
\item[{parameter x}]{the \ocamlinlinecode{x} coordinate}\end{description}%
141141
\begin{description}\kern-\topsep
@@ -144,7 +144,7 @@ \subsubsection{Basic type and value stuff with advanced doc comments\label{basic
144144
\end{ocamlindent}%
145145
\medbreak
146146
\label{module-Ocamlary-val-fun_fun_fun}\ocamlcodefragment{\ocamltag{keyword}{val} fun\_\allowbreak{}fun\_\allowbreak{}fun : ((int,\allowbreak{} int) \hyperref[module-Ocamlary-type-a_function]{\ocamlinlinecode{a\_\allowbreak{}function}},\allowbreak{} (unit,\allowbreak{} unit) \hyperref[module-Ocamlary-type-a_function]{\ocamlinlinecode{a\_\allowbreak{}function}}) \hyperref[module-Ocamlary-type-a_function]{\ocamlinlinecode{a\_\allowbreak{}function}}}\\
147-
\label{module-Ocamlary-val-fun_maybe}\ocamlcodefragment{\ocamltag{keyword}{val} fun\_\allowbreak{}maybe : ?yes:unit \ocamltag{arrow}{$\rightarrow$} unit \ocamltag{arrow}{$\rightarrow$} int}\\
147+
\label{module-Ocamlary-val-fun_maybe}\ocamlcodefragment{\ocamltag{keyword}{val} fun\_\allowbreak{}maybe : \ocamltag{optlabel}{?yes}:unit \ocamltag{arrow}{$\rightarrow$} unit \ocamltag{arrow}{$\rightarrow$} int}\\
148148
\label{module-Ocamlary-val-not_found}\ocamlcodefragment{\ocamltag{keyword}{val} not\_\allowbreak{}found : unit \ocamltag{arrow}{$\rightarrow$} unit}\begin{ocamlindent}\begin{description}\kern-\topsep
149149
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
150150
\item[{raises \ocamlinlinecode{Not\_\allowbreak{}found}}]{That's all it does}\end{description}%

‎test/generators/latex/Type.tex

+3-3
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ \section{Module \ocamlinlinecode{Type}}\label{module-Type}%
66
\label{module-Type-type-constructor}\ocamlcodefragment{\ocamltag{keyword}{type} 'a constructor = \ocamltag{type-var}{'a}}\\
77
\label{module-Type-type-arrow}\ocamlcodefragment{\ocamltag{keyword}{type} arrow = int \ocamltag{arrow}{$\rightarrow$} int}\\
88
\label{module-Type-type-higher_order}\ocamlcodefragment{\ocamltag{keyword}{type} higher\_\allowbreak{}order = (int \ocamltag{arrow}{$\rightarrow$} int) \ocamltag{arrow}{$\rightarrow$} int}\\
9-
\label{module-Type-type-labeled}\ocamlcodefragment{\ocamltag{keyword}{type} labeled = l:int \ocamltag{arrow}{$\rightarrow$} int}\\
10-
\label{module-Type-type-optional}\ocamlcodefragment{\ocamltag{keyword}{type} optional = ?l:int \ocamltag{arrow}{$\rightarrow$} int}\\
11-
\label{module-Type-type-labeled_higher_order}\ocamlcodefragment{\ocamltag{keyword}{type} labeled\_\allowbreak{}higher\_\allowbreak{}order = (l:int \ocamltag{arrow}{$\rightarrow$} int) \ocamltag{arrow}{$\rightarrow$} (?l:int \ocamltag{arrow}{$\rightarrow$} int) \ocamltag{arrow}{$\rightarrow$} int}\\
9+
\label{module-Type-type-labeled}\ocamlcodefragment{\ocamltag{keyword}{type} labeled = \ocamltag{label}{l}:int \ocamltag{arrow}{$\rightarrow$} int}\\
10+
\label{module-Type-type-optional}\ocamlcodefragment{\ocamltag{keyword}{type} optional = \ocamltag{optlabel}{?l}:int \ocamltag{arrow}{$\rightarrow$} int}\\
11+
\label{module-Type-type-labeled_higher_order}\ocamlcodefragment{\ocamltag{keyword}{type} labeled\_\allowbreak{}higher\_\allowbreak{}order = (\ocamltag{label}{l}:int \ocamltag{arrow}{$\rightarrow$} int) \ocamltag{arrow}{$\rightarrow$} (\ocamltag{optlabel}{?l}:int \ocamltag{arrow}{$\rightarrow$} int) \ocamltag{arrow}{$\rightarrow$} int}\\
1212
\label{module-Type-type-pair}\ocamlcodefragment{\ocamltag{keyword}{type} pair = int * int}\\
1313
\label{module-Type-type-parens_dropped}\ocamlcodefragment{\ocamltag{keyword}{type} parens\_\allowbreak{}dropped = int * int}\\
1414
\label{module-Type-type-triple}\ocamlcodefragment{\ocamltag{keyword}{type} triple = int * int * int}\\

‎test/generators/man/Bugs.3o

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Bugs
1313
.nf
1414
\f[CB]type\fR 'a opt = \f[CB]'a\fR option
1515
.sp
16-
\f[CB]val\fR foo : ?bar:\f[CB]'a\fR \f[CB]\->\fR unit \f[CB]\->\fR unit
16+
\f[CB]val\fR foo : \f[CB]?bar\fR:\f[CB]'a\fR \f[CB]\->\fR unit \f[CB]\->\fR unit
1717
.fi
1818
.br
1919
.ti +2

‎test/generators/man/Bugs_pre_410.3o

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Bugs_pre_410
1313
.nf
1414
\f[CB]type\fR 'a opt' = int option
1515
.sp
16-
\f[CB]val\fR foo' : ?bar:\f[CB]'a\fR \f[CB]\->\fR unit \f[CB]\->\fR unit
16+
\f[CB]val\fR foo' : \f[CB]?bar\fR:\f[CB]'a\fR \f[CB]\->\fR unit \f[CB]\->\fR unit
1717
.fi
1818
.br
1919
.ti +2

‎test/generators/man/Ocamlary.3o

+2-2
Original file line numberDiff line numberDiff line change
@@ -367,7 +367,7 @@ Unary exception constructor over binary tuple
367367
\f[CI]a_function\fR is this type and \f[CI]a_function\fR is the value below\.
368368
.nf
369369
.sp
370-
\f[CB]val\fR a_function : x:int \f[CB]\->\fR int
370+
\f[CB]val\fR a_function : \f[CB]x\fR:int \f[CB]\->\fR int
371371
.fi
372372
.br
373373
.ti +2
@@ -382,7 +382,7 @@ This is a_function with param and return type\.
382382
.sp
383383
\f[CB]val\fR fun_fun_fun : ((int, int) a_function, (unit, unit) a_function) a_function
384384
.sp
385-
\f[CB]val\fR fun_maybe : ?yes:unit \f[CB]\->\fR unit \f[CB]\->\fR int
385+
\f[CB]val\fR fun_maybe : \f[CB]?yes\fR:unit \f[CB]\->\fR unit \f[CB]\->\fR int
386386
.sp
387387
\f[CB]val\fR not_found : unit \f[CB]\->\fR unit
388388
.fi

‎test/generators/man/Type.3o

+3-3
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,11 @@ Some documentation\.
2828
.sp
2929
\f[CB]type\fR higher_order = (int \f[CB]\->\fR int) \f[CB]\->\fR int
3030
.sp
31-
\f[CB]type\fR labeled = l:int \f[CB]\->\fR int
31+
\f[CB]type\fR labeled = \f[CB]l\fR:int \f[CB]\->\fR int
3232
.sp
33-
\f[CB]type\fR optional = ?l:int \f[CB]\->\fR int
33+
\f[CB]type\fR optional = \f[CB]?l\fR:int \f[CB]\->\fR int
3434
.sp
35-
\f[CB]type\fR labeled_higher_order = (l:int \f[CB]\->\fR int) \f[CB]\->\fR (?l:int \f[CB]\->\fR int) \f[CB]\->\fR int
35+
\f[CB]type\fR labeled_higher_order = (\f[CB]l\fR:int \f[CB]\->\fR int) \f[CB]\->\fR (\f[CB]?l\fR:int \f[CB]\->\fR int) \f[CB]\->\fR int
3636
.sp
3737
\f[CB]type\fR pair = int * int
3838
.sp

0 commit comments

Comments
 (0)