Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Span labels in function arguments (?id: and id:) #990

Merged
merged 1 commit into from
Sep 4, 2023
Merged

Span labels in function arguments (?id: and id:) #990

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions src/document/generator.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,12 @@ open Types
module O = Codefmt
open O.Infix

let tag tag t = O.span ~attr:tag t

let label t =
match t with
| Odoc_model.Lang.TypeExpr.Label s -> O.txt s
| Optional s -> O.txt "?" ++ O.txt s

let tag tag t = O.span ~attr:tag t
| Odoc_model.Lang.TypeExpr.Label s -> tag "label" (O.txt s)
| Optional s -> tag "optlabel" (O.txt "?" ++ O.txt s)

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

Expand Down
9 changes: 9 additions & 0 deletions src/html_support_files/odoc.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,7 @@
--toc-list-border: #ccc;

--spec-summary-border-color: #5c9cf5;
--spec-label-color: green;
--spec-summary-background: var(--code-background);
--spec-summary-hover-background: #ebeff2;
--spec-details-after-background: rgba(0, 4, 15, 0.05);
Expand Down Expand Up @@ -158,6 +159,8 @@
--hljs-type: #ac885b;
--hljs-meta: #82aaff;
--hljs-variable: #cf6a4c;

--spec-label-color: lightgreen;
}

@media (prefers-color-scheme: dark) {
Expand Down Expand Up @@ -204,6 +207,8 @@
--hljs-type: #ac885b;
--hljs-meta: #82aaff;
--hljs-variable: #cf6a4c;

--spec-label-color: lightgreen;
}
}

Expand Down Expand Up @@ -525,6 +530,10 @@ p a > code, li a > code {
padding: 0.35em 0.5em;
}

.spec .label, .spec .optlabel {
color: var(--spec-label-color);
}

li:not(:last-child) > .def-doc {
margin-bottom: 15px;
}
Expand Down
24 changes: 12 additions & 12 deletions src/html_support_files/odoc_html_support_files.ml
View file
Open in desktop

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions test/generators/html/Bugs.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@ <h1>Module <code><span>Bugs</span></code></h1>
<a href="#val-foo" class="anchor"></a>
<code>
<span><span class="keyword">val</span> foo :
<span>?bar:<span class="type-var">'a</span>
<span class="arrow">&#45;&gt;</span>
<span><span class="optlabel">?bar</span>:
<span class="type-var">'a</span> <span class="arrow">&#45;&gt;</span>
</span> <span>unit <span class="arrow">&#45;&gt;</span></span>
unit
</span>
Expand Down
4 changes: 2 additions & 2 deletions test/generators/html/Bugs_pre_410.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ <h1>Module <code><span>Bugs_pre_410</span></code></h1>
<a href="#val-foo'" class="anchor"></a>
<code>
<span><span class="keyword">val</span> foo' :
<span>?bar:<span class="type-var">'a</span>
<span class="arrow">&#45;&gt;</span>
<span><span class="optlabel">?bar</span>:
<span class="type-var">'a</span> <span class="arrow">&#45;&gt;</span>
</span> <span>unit <span class="arrow">&#45;&gt;</span></span>
unit
</span>
Expand Down
10 changes: 7 additions & 3 deletions test/generators/html/Ocamlary.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -388,7 +388,9 @@ <h4 id="basic-type-and-value-stuff-with-advanced-doc-comments">
<a href="#val-a_function" class="anchor"></a>
<code>
<span><span class="keyword">val</span> a_function :
<span>x:int <span class="arrow">&#45;&gt;</span></span> int
<span><span class="label">x</span>:int
<span class="arrow">&#45;&gt;</span>
</span> int
</span>
</code>
</div>
Expand Down Expand Up @@ -430,8 +432,10 @@ <h4 id="basic-type-and-value-stuff-with-advanced-doc-comments">
<a href="#val-fun_maybe" class="anchor"></a>
<code>
<span><span class="keyword">val</span> fun_maybe :
<span>?yes:unit <span class="arrow">&#45;&gt;</span></span>
<span>unit <span class="arrow">&#45;&gt;</span></span> int
<span><span class="optlabel">?yes</span>:unit
<span class="arrow">&#45;&gt;</span>
</span> <span>unit <span class="arrow">&#45;&gt;</span></span>
int
</span>
</code>
</div>
Expand Down
20 changes: 16 additions & 4 deletions test/generators/html/Type.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,10 @@ <h1>Module <code><span>Type</span></code></h1>
<div class="spec type anchored" id="type-labeled">
<a href="#type-labeled" class="anchor"></a>
<code><span><span class="keyword">type</span> labeled</span>
<span> = <span>l:int <span class="arrow">&#45;&gt;</span></span> int
<span> =
<span><span class="label">l</span>:int
<span class="arrow">&#45;&gt;</span>
</span> int
</span>
</code>
</div>
Expand All @@ -77,7 +80,10 @@ <h1>Module <code><span>Type</span></code></h1>
<div class="spec type anchored" id="type-optional">
<a href="#type-optional" class="anchor"></a>
<code><span><span class="keyword">type</span> optional</span>
<span> = <span>?l:int <span class="arrow">&#45;&gt;</span></span> int
<span> =
<span><span class="optlabel">?l</span>:int
<span class="arrow">&#45;&gt;</span>
</span> int
</span>
</code>
</div>
Expand All @@ -89,11 +95,17 @@ <h1>Module <code><span>Type</span></code></h1>
<span><span class="keyword">type</span> labeled_higher_order</span>
<span> =
<span>
<span>(<span>l:int <span class="arrow">&#45;&gt;</span></span> int)
<span>(
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not related to this PR but this reminds me that the --indent option breaks the formatting: ocsigen/tyxml#288

<span><span class="label">l</span>:int
<span class="arrow">&#45;&gt;</span>
</span> int)
</span> <span class="arrow">&#45;&gt;</span>
</span>
<span>
<span>(<span>?l:int <span class="arrow">&#45;&gt;</span></span> int)
<span>(
<span><span class="optlabel">?l</span>:int
<span class="arrow">&#45;&gt;</span>
</span> int)
</span> <span class="arrow">&#45;&gt;</span>
</span> int
</span>
Expand Down
2 changes: 1 addition & 1 deletion test/generators/latex/Bugs.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
\section{Module \ocamlinlinecode{Bugs}}\label{module-Bugs}%
\label{module-Bugs-type-opt}\ocamlcodefragment{\ocamltag{keyword}{type} 'a opt = \ocamltag{type-var}{'a} option}\\
\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}%
\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}%
\medbreak


2 changes: 1 addition & 1 deletion test/generators/latex/Bugs_pre_410.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
\section{Module \ocamlinlinecode{Bugs\_\allowbreak{}pre\_\allowbreak{}410}}\label{module-Bugs_pre_410}%
\label{module-Bugs_pre_410-type-opt'}\ocamlcodefragment{\ocamltag{keyword}{type} 'a opt' = int option}\\
\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}%
\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}%
\medbreak


4 changes: 2 additions & 2 deletions test/generators/latex/Ocamlary.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ \subsubsection{Basic exception stuff\label{basic-exception-stuff}}%
\subsubsection{Basic type and value stuff with advanced doc comments\label{basic-type-and-value-stuff-with-advanced-doc-comments}}%
\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}%
\medbreak
\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
\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
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{parameter x}]{the \ocamlinlinecode{x} coordinate}\end{description}%
\begin{description}\kern-\topsep
Expand All @@ -144,7 +144,7 @@ \subsubsection{Basic type and value stuff with advanced doc comments\label{basic
\end{ocamlindent}%
\medbreak
\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}}}\\
\label{module-Ocamlary-val-fun_maybe}\ocamlcodefragment{\ocamltag{keyword}{val} fun\_\allowbreak{}maybe : ?yes:unit \ocamltag{arrow}{$\rightarrow$} unit \ocamltag{arrow}{$\rightarrow$} int}\\
\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}\\
\label{module-Ocamlary-val-not_found}\ocamlcodefragment{\ocamltag{keyword}{val} not\_\allowbreak{}found : unit \ocamltag{arrow}{$\rightarrow$} unit}\begin{ocamlindent}\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{raises \ocamlinlinecode{Not\_\allowbreak{}found}}]{That's all it does}\end{description}%
Expand Down
6 changes: 3 additions & 3 deletions test/generators/latex/Type.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ \section{Module \ocamlinlinecode{Type}}\label{module-Type}%
\label{module-Type-type-constructor}\ocamlcodefragment{\ocamltag{keyword}{type} 'a constructor = \ocamltag{type-var}{'a}}\\
\label{module-Type-type-arrow}\ocamlcodefragment{\ocamltag{keyword}{type} arrow = int \ocamltag{arrow}{$\rightarrow$} int}\\
\label{module-Type-type-higher_order}\ocamlcodefragment{\ocamltag{keyword}{type} higher\_\allowbreak{}order = (int \ocamltag{arrow}{$\rightarrow$} int) \ocamltag{arrow}{$\rightarrow$} int}\\
\label{module-Type-type-labeled}\ocamlcodefragment{\ocamltag{keyword}{type} labeled = l:int \ocamltag{arrow}{$\rightarrow$} int}\\
\label{module-Type-type-optional}\ocamlcodefragment{\ocamltag{keyword}{type} optional = ?l:int \ocamltag{arrow}{$\rightarrow$} int}\\
\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}\\
\label{module-Type-type-labeled}\ocamlcodefragment{\ocamltag{keyword}{type} labeled = \ocamltag{label}{l}:int \ocamltag{arrow}{$\rightarrow$} int}\\
\label{module-Type-type-optional}\ocamlcodefragment{\ocamltag{keyword}{type} optional = \ocamltag{optlabel}{?l}:int \ocamltag{arrow}{$\rightarrow$} int}\\
\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}\\
\label{module-Type-type-pair}\ocamlcodefragment{\ocamltag{keyword}{type} pair = int * int}\\
\label{module-Type-type-parens_dropped}\ocamlcodefragment{\ocamltag{keyword}{type} parens\_\allowbreak{}dropped = int * int}\\
\label{module-Type-type-triple}\ocamlcodefragment{\ocamltag{keyword}{type} triple = int * int * int}\\
Expand Down
2 changes: 1 addition & 1 deletion test/generators/man/Bugs.3o
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Bugs
.nf
\f[CB]type\fR 'a opt = \f[CB]'a\fR option
.sp
\f[CB]val\fR foo : ?bar:\f[CB]'a\fR \f[CB]\->\fR unit \f[CB]\->\fR unit
\f[CB]val\fR foo : \f[CB]?bar\fR:\f[CB]'a\fR \f[CB]\->\fR unit \f[CB]\->\fR unit
.fi
.br
.ti +2
Expand Down
2 changes: 1 addition & 1 deletion test/generators/man/Bugs_pre_410.3o
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Bugs_pre_410
.nf
\f[CB]type\fR 'a opt' = int option
.sp
\f[CB]val\fR foo' : ?bar:\f[CB]'a\fR \f[CB]\->\fR unit \f[CB]\->\fR unit
\f[CB]val\fR foo' : \f[CB]?bar\fR:\f[CB]'a\fR \f[CB]\->\fR unit \f[CB]\->\fR unit
.fi
.br
.ti +2
Expand Down
4 changes: 2 additions & 2 deletions test/generators/man/Ocamlary.3o
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -367,7 +367,7 @@ Unary exception constructor over binary tuple
\f[CI]a_function\fR is this type and \f[CI]a_function\fR is the value below\.
.nf
.sp
\f[CB]val\fR a_function : x:int \f[CB]\->\fR int
\f[CB]val\fR a_function : \f[CB]x\fR:int \f[CB]\->\fR int
.fi
.br
.ti +2
Expand All @@ -382,7 +382,7 @@ This is a_function with param and return type\.
.sp
\f[CB]val\fR fun_fun_fun : ((int, int) a_function, (unit, unit) a_function) a_function
.sp
\f[CB]val\fR fun_maybe : ?yes:unit \f[CB]\->\fR unit \f[CB]\->\fR int
\f[CB]val\fR fun_maybe : \f[CB]?yes\fR:unit \f[CB]\->\fR unit \f[CB]\->\fR int
.sp
\f[CB]val\fR not_found : unit \f[CB]\->\fR unit
.fi
Expand Down
6 changes: 3 additions & 3 deletions test/generators/man/Type.3o
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,11 @@ Some documentation\.
.sp
\f[CB]type\fR higher_order = (int \f[CB]\->\fR int) \f[CB]\->\fR int
.sp
\f[CB]type\fR labeled = l:int \f[CB]\->\fR int
\f[CB]type\fR labeled = \f[CB]l\fR:int \f[CB]\->\fR int
.sp
\f[CB]type\fR optional = ?l:int \f[CB]\->\fR int
\f[CB]type\fR optional = \f[CB]?l\fR:int \f[CB]\->\fR int
.sp
\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
\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
.sp
\f[CB]type\fR pair = int * int
.sp
Expand Down