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

Signed-off-by: Paul-Elliot <[email protected]>

src/document/generator.ml

@@ -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 "opt-arg" (O.txt s)
+  | Optional s -> tag "named-arg" (O.txt "?" ++ O.txt s)
 
 let type_var tv = tag "type-var" (O.txt tv)
 

src/html_support_files/odoc.css

@@ -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);
@@ -158,6 +159,8 @@
   --hljs-type: #ac885b;
   --hljs-meta: #82aaff;
   --hljs-variable: #cf6a4c;
+
+  --spec-label-color: lightgreen;
 }
 
 @media (prefers-color-scheme: dark) {
@@ -204,6 +207,8 @@
     --hljs-type: #ac885b;
     --hljs-meta: #82aaff;
     --hljs-variable: #cf6a4c;
+
+    --spec-label-color: lightgreen;
   }
 }
 
@@ -525,6 +530,10 @@ p a > code, li a > code {
   padding: 0.35em 0.5em;
 }
 
+.spec .named-arg, .spec .opt-arg {
+  color: var(--spec-label-color);
+}
+
 li:not(:last-child) > .def-doc {
   margin-bottom: 15px;
 }

test/generators/html/Bugs.html

@@ -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="named-arg">?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>

test/generators/html/Ocamlary.html

@@ -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="opt-arg">x</span>:int 
+        <span class="arrow">&#45;&gt;</span>
+       </span> int
       </span>
      </code>
     </div>
@@ -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="named-arg">?yes</span>:unit 
+        <span class="arrow">&#45;&gt;</span>
+       </span> <span>unit <span class="arrow">&#45;&gt;</span></span>
+        int
       </span>
      </code>
     </div>

test/generators/html/Type.html

@@ -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="opt-arg">l</span>:int 
+        <span class="arrow">&#45;&gt;</span>
+       </span> int
       </span>
      </code>
     </div>
@@ -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="named-arg">?l</span>:int 
+        <span class="arrow">&#45;&gt;</span>
+       </span> int
       </span>
      </code>
     </div>
@@ -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>(
+         <span><span class="opt-arg">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="named-arg">?l</span>:int 
+          <span class="arrow">&#45;&gt;</span>
+         </span> int)
         </span> <span class="arrow">&#45;&gt;</span>
        </span> int
       </span>

test/generators/latex/Bugs.tex

@@ -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{named-arg}{?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
 
 

test/generators/latex/Ocamlary.tex

@@ -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{opt-arg}{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
@@ -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{named-arg}{?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}%

test/generators/latex/Type.tex

@@ -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{opt-arg}{l}:int \ocamltag{arrow}{$\rightarrow$} int}\\
+\label{module-Type-type-optional}\ocamlcodefragment{\ocamltag{keyword}{type} optional = \ocamltag{named-arg}{?l}:int \ocamltag{arrow}{$\rightarrow$} int}\\
+\label{module-Type-type-labeled_higher_order}\ocamlcodefragment{\ocamltag{keyword}{type} labeled\_\allowbreak{}higher\_\allowbreak{}order = (\ocamltag{opt-arg}{l}:int \ocamltag{arrow}{$\rightarrow$} int) \ocamltag{arrow}{$\rightarrow$} (\ocamltag{named-arg}{?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}\\

test/generators/man/Bugs.3o

@@ -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

test/generators/man/Ocamlary.3o

@@ -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
@@ -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 

test/generators/man/Type.3o

@@ -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