Skip to content

Make type definition copy-pastable with hidden comment delimiters. #626

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

Merged
merged 1 commit into from
Mar 11, 2021
Merged

Make type definition copy-pastable with hidden comment delimiters. #626

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
4 changes: 4 additions & 0 deletions src/document/ML.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,10 @@ module ML = Generator.Make (struct

let semicolon = false
end

module Comment = struct
let markers = ("(*", "*)")
end
end)

include ML
14 changes: 9 additions & 5 deletions src/document/generator.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -409,7 +409,8 @@ module Make (Syntax : SYNTAX) = struct
let anchor = Some url in
let rhs = Comment.to_ir fld.doc in
let doc = if not (Comment.has_doc fld.doc) then [] else rhs in
DocumentedSrc.Documented { anchor; attrs; code; doc })
let markers = Syntax.Comment.markers in
DocumentedSrc.Documented { anchor; attrs; code; doc; markers })
in
let content =
O.documentedSrc (O.txt "{") @ rows @ O.documentedSrc (O.txt "}")
Expand Down Expand Up @@ -513,7 +514,8 @@ module Make (Syntax : SYNTAX) = struct
let doc =
if not (Comment.has_doc cstr.doc) then [] else rhs
in
DocumentedSrc.Nested { anchor; attrs; code; doc })
let markers = Syntax.Comment.markers in
DocumentedSrc.Nested { anchor; attrs; code; doc; markers })
in
rows

Expand All @@ -528,7 +530,8 @@ module Make (Syntax : SYNTAX) = struct
O.documentedSrc (O.txt "| ") @ constructor id t.args t.res
in
let doc = Comment.to_ir t.doc in
DocumentedSrc.Nested { anchor; attrs; code; doc }
let markers = Syntax.Comment.markers in
DocumentedSrc.Nested { anchor; attrs; code; doc; markers }

let extension (t : Odoc_model.Lang.Extension.t) =
let content =
Expand Down Expand Up @@ -596,20 +599,21 @@ module Make (Syntax : SYNTAX) = struct
),
match doc with [] -> None | _ -> Some (Comment.to_ir doc) ) )
in
let markers = Syntax.Comment.markers in
try
let url = Url.Anchor.polymorphic_variant ~type_ident item in
let attrs = [ "def"; url.kind ] in
let anchor = Some url in
let code = O.code (O.txt "| ") @ cstr in
let doc = match doc with None -> [] | Some doc -> doc in
DocumentedSrc.Documented { attrs; anchor; code; doc }
DocumentedSrc.Documented { attrs; anchor; code; doc; markers }
with Failure s ->
Printf.eprintf "ERROR: %s\n%!" s;
let code = O.code (O.txt "| ") @ cstr in
let attrs = [ "def"; kind_approx ] in
let doc = [] in
let anchor = None in
DocumentedSrc.Documented { attrs; anchor; code; doc }
DocumentedSrc.Documented { attrs; anchor; code; doc; markers }
in
let variants = List.map row t.elements in
let intro, ending =
Expand Down
4 changes: 4 additions & 0 deletions src/document/generator_signatures.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,10 @@ module type SYNTAX = sig

val semicolon : bool
end

module Comment : sig
val markers : string * string
end
end

module type GENERATOR = sig
Expand Down
4 changes: 4 additions & 0 deletions src/document/reason.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,10 @@ module Reason = Generator.Make (struct

let semicolon = true
end

module Comment = struct
let markers = ("/*", "*/")
end
end)

include Reason
1 change: 1 addition & 0 deletions src/document/types.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@ and DocumentedSrc : sig
anchor : Url.Anchor.t option;
code : 'a;
doc : Block.t;
markers : string * string;
}

type t = one list
Expand Down
32 changes: 24 additions & 8 deletions src/html/generator.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,10 +222,12 @@ let rec documentedSrc ~resolve (t : DocumentedSrc.t) : item Html.elt list =
in
let take_descr l =
Doctree.Take.until l ~classify:(function
| Documented { attrs; anchor; code; doc } ->
Accum [ { DocumentedSrc.attrs; anchor; code = `D code; doc } ]
| Nested { attrs; anchor; code; doc } ->
Accum [ { DocumentedSrc.attrs; anchor; code = `N code; doc } ]
| Documented { attrs; anchor; code; doc; markers } ->
Accum
[ { DocumentedSrc.attrs; anchor; code = `D code; doc; markers } ]
| Nested { attrs; anchor; code; doc; markers } ->
Accum
[ { DocumentedSrc.attrs; anchor; code = `N code; doc; markers } ]
| _ -> Stop_and_keep)
in
let rec to_html t : item Html.elt list =
Expand All @@ -237,16 +239,30 @@ let rec documentedSrc ~resolve (t : DocumentedSrc.t) : item Html.elt list =
| Subpage subp :: _ -> subpage ~resolve subp
| (Documented _ | Nested _) :: _ ->
let l, _, rest = take_descr t in
let one { DocumentedSrc.attrs; anchor; code; doc } =
let one { DocumentedSrc.attrs; anchor; code; doc; markers } =
let content =
match code with
| `D code -> (inline ~resolve code :> item Html.elt list)
| `N n -> to_html n
in
let doc =
Utils.optional_elt Html.td
~a:(class_ [ "def-doc" ])
(block ~resolve doc)
match doc with
| [] -> []
| doc ->
let opening, closing = markers in
[
Html.td
~a:(class_ [ "def-doc" ])
( Html.span
~a:(class_ [ "comment-delim" ])
[ Html.txt opening ]
:: block ~resolve doc
@ [
Html.span
~a:(class_ [ "comment-delim" ])
[ Html.txt closing ];
] );
]
in
let a, link = mk_anchor anchor in
let content =
Expand Down
26 changes: 22 additions & 4 deletions src/latex/generator.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,10 +359,28 @@ let rec documentedSrc (t : DocumentedSrc.t) =
| (Documented _ | Nested _) :: _ ->
let take_descr l =
Doctree.Take.until l ~classify:(function
| Documented { attrs; anchor; code; doc } ->
Accum [ { DocumentedSrc.attrs; anchor; code = `D code; doc } ]
| Nested { attrs; anchor; code; doc } ->
Accum [ { DocumentedSrc.attrs; anchor; code = `N code; doc } ]
| Documented { attrs; anchor; code; doc; markers } ->
Accum
[
{
DocumentedSrc.attrs;
anchor;
code = `D code;
doc;
markers;
};
]
| Nested { attrs; anchor; code; doc; markers } ->
Accum
[
{
DocumentedSrc.attrs;
anchor;
code = `N code;
doc;
markers;
};
]
| _ -> Stop_and_keep)
in
let l, _, rest = take_descr t in
Expand Down
16 changes: 16 additions & 0 deletions src/odoc/etc/odoc.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -351,6 +351,22 @@ h4 {
font-size: 1.12em;
}

/* Comment delimiters, hidden but accessible to screen readers and
selected for copy/pasting */

/* Taken from bootstrap */
/* See also https://stackoverflow.com/a/27769435/4220738 */
.comment-delim {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border: 0;
}
Copy link
Contributor

Choose a reason for hiding this comment

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

Just FTR I personally dislike cargo-culting CSS, that usually leads to pains down the road :-) But based on @Drup understanding it seems that in odig's stylesheets you can boil that down to:

.spec .def-doc .comment-delim /* make them invisible yet copy-pastable */
{ position: absolute; width: 1px; height: 1px; overflow: hidden; }

(Tested in all browsers major browsers)

Copy link
Contributor Author

@Drup Drup Mar 12, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

Yeah, I also think we can shorten it, but there is a "belt and braces" aspect: we make it invisible and put it somewhere else. :)


/* Preformatted and code */

Expand Down
4 changes: 4 additions & 0 deletions test/html/expect/test_package+ml/Labels/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,9 +150,11 @@ <h2 id="L2">
<a href="#type-u.A'" class="anchor"></a><code><span>| </span><span><span class="constructor">A'</span></span></code>
</td>
<td class="def-doc">
<span class="comment-delim">(*</span>
<p>
Attached to constructor
</p>
<span class="comment-delim">*)</span>
</td>
</tr>
</tbody>
Expand All @@ -169,9 +171,11 @@ <h2 id="L2">
<a href="#type-v.f" class="anchor"></a><code><span>f : <a href="#type-t">t</a>;</span></code>
</td>
<td class="def-doc">
<span class="comment-delim">(*</span>
<p>
Attached to field
</p>
<span class="comment-delim">*)</span>
</td>
</tr>
</tbody>
Expand Down
Loading