Skip to content

Commit

Permalink
vitepress: add target self for api links
Browse files Browse the repository at this point in the history
  • Loading branch information
jchavarri committed Feb 9, 2024
1 parent c66906c commit 300c4f8
Show file tree
Hide file tree
Showing 3 changed files with 51 additions and 43 deletions.
10 changes: 6 additions & 4 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,13 @@ href="./api/ml/melange/Stdlib"><code>Stdlib</code> library</a><a
class="text-reasonml" target="_self"
href="./api/re/melange/Stdlib"><code>Stdlib</code> library</a>
- Bindings to several browser and Node JavaScript APIs in the <a
class="text-ocaml" href="./api/ml/melange/Js"><code>Js</code> library</a><a
class="text-reasonml" href="./api/re/melange/Js"><code>Js</code> library</a>
class="text-ocaml" target="_self" href="./api/ml/melange/Js"><code>Js</code>
library</a><a class="text-reasonml" target="_self"
href="./api/re/melange/Js"><code>Js</code> library</a>
- Data structures and collection types in the <a class="text-ocaml"
href="./api/ml/melange/Belt"><code>Belt</code> library</a><a
class="text-reasonml" href="./api/re/melange/Belt"><code>Belt</code> library</a>
target="_self" href="./api/ml/melange/Belt"><code>Belt</code> library</a><a
class="text-reasonml" target="_self"
href="./api/re/melange/Belt"><code>Belt</code> library</a>

Using one or the other will depend on your application requirements, how much
integration you need with existing JavaScript libraries, or other specific
Expand Down
82 changes: 44 additions & 38 deletions docs/communicate-with-javascript.md
Original file line number Diff line number Diff line change
Expand Up @@ -397,11 +397,12 @@ class="text-reasonml">\-\></code>.
As its name suggests, the pipe first operator is better suited for functions
where the data is passed as the first argument.

The functions in the <a class="text-ocaml"
The functions in the <a class="text-ocaml" target="_self"
href="./api/ml/melange/Belt"><code>Belt</code> library</a><a
class="text-reasonml" href="./api/re/melange/Belt"><code>Belt</code>
library</a> included with Melange have been designed with the data-first
convention in mind, so they work best with the pipe first operator.
class="text-reasonml" target="_self"
href="./api/re/melange/Belt"><code>Belt</code> library</a> included with Melange
have been designed with the data-first convention in mind, so they work best
with the pipe first operator.

For example, we can rewrite the example above using `Belt.List.map` and the pipe
first operator:
Expand Down Expand Up @@ -470,8 +471,8 @@ This is how each Melange type is converted into JavaScript values:
| array | array |
| tuple `(3, 4)` | array `[3, 4]` |
| bool | boolean |
| <a class="text-ocaml" href="./api/ml/melange/Js/Nullable">Js.Nullable.t</a><a class="text-reasonml" href="./api/re/melange/Js/Nullable">Js.Nullable.t</a> | `null` / `undefined` |
| <a class="text-ocaml" href="./api/ml/melange/Js/Re">Js.Re.t</a><a class="text-reasonml" href="./api/re/melange/Js/Re">Js.Re.t</a> | [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) |
| <a class="text-ocaml" target="_self" href="./api/ml/melange/Js/Nullable">Js.Nullable.t</a><a class="text-reasonml" target="_self" href="./api/re/melange/Js/Nullable">Js.Nullable.t</a> | `null` / `undefined` |
| <a class="text-ocaml" target="_self" href="./api/ml/melange/Js/Re">Js.Re.t</a><a class="text-reasonml" target="_self" href="./api/re/melange/Js/Re">Js.Re.t</a> | [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) |
| Option.t `None` | `undefined` |
| Option.t <code class="text-ocaml">Some( Some .. Some (None))</code><code class="text-reasonml">Some(Some( .. Some(None)))</code> | internal representation |
| Option.t <code class="text-ocaml">Some 2</code><code class="text-reasonml">Some(2)</code> | `2` |
Expand Down Expand Up @@ -586,13 +587,14 @@ You can surround the interpolation variable in parentheses too: `{j|你
好,$(world)|j}`.

To work with strings, the Melange standard library provides some utilities in
the <a class="text-ocaml"
the <a class="text-ocaml" target="_self"
href="./api/ml/melange/Stdlib/String"><code>Stdlib.String</code> module</a><a
class="text-reasonml"
href="./api/re/melange/Stdlib/String"><code>Stdlib.String</code> module</a>.
The bindings to the native JavaScript functions to work with strings are in the
<a class="text-ocaml" href="./api/ml/melange/Js/String"><code>Js.String</code>
module</a><a class="text-reasonml"
class="text-reasonml" target="_self"
href="./api/re/melange/Stdlib/String"><code>Stdlib.String</code> module</a>. The
bindings to the native JavaScript functions to work with strings are in the <a
class="text-ocaml" target="_self"
href="./api/ml/melange/Js/String"><code>Js.String</code> module</a><a
class="text-reasonml" target="_self"
href="./api/re/melange/Js/String"><code>Js.String</code> module</a>.

#### Floating-point numbers
Expand All @@ -604,12 +606,13 @@ same encoding as [JavaScript
numbers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_encoding),
so values of these types can be used transparently between Melange code and
JavaScript code. The Melange standard library provides a <a class="text-ocaml"
href="./api/ml/melange/Stdlib/Float"><code>Stdlib.Float</code> module</a><a
class="text-reasonml"
target="_self" href="./api/ml/melange/Stdlib/Float"><code>Stdlib.Float</code>
module</a><a class="text-reasonml" target="_self"
href="./api/re/melange/Stdlib/Float"><code>Stdlib.Float</code> module</a>. The
bindings to the JavaScript APIs that manipulate float values can be found in the
<a class="text-ocaml" href="./api/ml/melange/Js/Float"><code>Js.Float</code>
module</a><a class="text-reasonml"
<a class="text-ocaml" target="_self"
href="./api/ml/melange/Js/Float"><code>Js.Float</code> module</a><a
class="text-reasonml" target="_self"
href="./api/re/melange/Js/Float"><code>Js.Float</code> module</a>.

#### Integers
Expand All @@ -626,14 +629,14 @@ allowing for a larger range of representable integers in JavaScript compared to
Melange. When dealing with large numbers, it is advisable to use floats instead.
For instance, floats are used in bindings like `Js.Date`.

The Melange standard library provides a <a class="text-ocaml"
The Melange standard library provides a <a class="text-ocaml" target="_self"
href="./api/ml/melange/Stdlib/Int"><code>Stdlib.Int</code> module</a><a
class="text-reasonml"
class="text-reasonml" target="_self"
href="./api/re/melange/Stdlib/Int"><code>Stdlib.Int</code> module</a>. The
bindings to work with JavaScript integers are in the <a class="text-ocaml"
href="./api/ml/melange/Js/Int"><code>Js.Int</code> module</a><a
class="text-reasonml" href="./api/re/melange/Js/Int"><code>Js.Int</code>
module</a>.
target="_self" href="./api/ml/melange/Js/Int"><code>Js.Int</code> module</a><a
class="text-reasonml" target="_self"
href="./api/re/melange/Js/Int"><code>Js.Int</code> module</a>.

#### Arrays

Expand All @@ -643,14 +646,15 @@ arrays, all the values in a Melange array need to have the same type.
Another difference is that OCaml arrays are fixed-sized, but on Melange side
this constraint is relaxed. You can change an array’s length using functions
like `Js.Array.push`, available in the bindings to the JavaScript APIs in the <a
class="text-ocaml" href="./api/ml/melange/Js/Array"><code>Js.Array</code>
module</a><a class="text-reasonml"
class="text-ocaml" target="_self"
href="./api/ml/melange/Js/Array"><code>Js.Array</code> module</a><a
class="text-reasonml" target="_self"
href="./api/re/melange/Js/Array"><code>Js.Array</code> module</a>.

Melange standard library also has a module to work with arrays, available in the
<a class="text-ocaml"
<a class="text-ocaml" target="_self"
href="./api/ml/melange/Stdlib/Array"><code>Stdlib.Array</code> module</a><a
class="text-reasonml"
class="text-reasonml" target="_self"
href="./api/re/melange/Stdlib/Array"><code>Stdlib.Array</code> module</a>.

#### Tuples
Expand Down Expand Up @@ -714,8 +718,9 @@ var r = /b/g;
```

A regular expression like the above is of type `Js.Re.t`. The <a
class="text-ocaml" href="./api/ml/melange/Js/Re"><code>Js.Re</code>
module</a><a class="text-reasonml"
class="text-ocaml" target="_self"
href="./api/ml/melange/Js/Re"><code>Js.Re</code> module</a><a
class="text-reasonml" target="_self"
href="./api/re/melange/Js/Re"><code>Js.Re</code> module</a> provides the
bindings to the JavaScript functions that operate over regular expressions.

Expand All @@ -730,15 +735,15 @@ them before doing so.
[some helpers](#generate-getters-setters-and-constructors) to do so.
- Exceptions
- Option (a variant type): Better use the `Js.Nullable.fromOption` and
`Js.Nullable.toOption` functions in the <a class="text-ocaml"
`Js.Nullable.toOption` functions in the <a class="text-ocaml" target="_self"
href="./api/ml/melange/Js/Nullable"><code>Js.Nullable</code> module</a><a
class="text-reasonml"
class="text-reasonml" target="_self"
href="./api/re/melange/Js/Nullable"><code>Js.Nullable</code> module</a> to
transform them into either `null` or `undefined` values.
- List (also a variant type): use `Array.of_list` and `Array.to_list` in the <a
class="text-ocaml"
class="text-ocaml" target="_self"
href="./api/ml/melange/Stdlib/Array"><code>Stdlib.Array</code> module</a><a
class="text-reasonml"
class="text-reasonml" target="_self"
href="./api/re/melange/Stdlib/Array"><code>Stdlib.Array</code> module</a>.
- Character
- Int64
Expand Down Expand Up @@ -879,8 +884,8 @@ let f: unit => int = ([%mel.raw "function() {return 1}"]: unit => int);
```

Using <span class="text-ocaml">two percentage signs (`[%%mel.raw
"xxx"]`)</span><span class="text-reasonml">the extension name without
square brackets (`%mel.raw "xxx"`)</span> is reserved for definitions in a
"xxx"]`)</span><span class="text-reasonml">the extension name without square
brackets (`%mel.raw "xxx"`)</span> is reserved for definitions in a
[structure](https://v2.ocaml.org/manual/moduleexamples.html#s:module:structures)
or [signature](https://v2.ocaml.org/manual/moduleexamples.html#s%3Asignature).

Expand Down Expand Up @@ -1388,10 +1393,11 @@ Sometimes JavaScript objects are used as dictionaries. In these cases:

For this particular use case of JavaScript objects, Melange exposes a specific
type `Js.Dict.t`. The values and functions to work with values of this type are
defined in the <a class="text-ocaml"
defined in the <a class="text-ocaml" target="_self"
href="./api/ml/melange/Js/Dict"><code>Js.Dict</code> module</a><a
class="text-reasonml" href="./api/re/melange/Js/Dict"><code>Js.Dict</code>
module</a>, with operations like `get`, `set`, etc.
class="text-reasonml" target="_self"
href="./api/re/melange/Js/Dict"><code>Js.Dict</code> module</a>, with operations
like `get`, `set`, etc.

Values of the type `Js.Dict.t` compile to JavaScript objects.

Expand Down Expand Up @@ -1466,8 +1472,8 @@ let () = clearTimeout(id);

> **_NOTE:_** The bindings to `setTimeout` and `clearTimeout` are shown here for
> learning purposes, but they are already available in the <a class="text-ocaml"
> href="./api/ml/melange/Js/Global"><code>Js.Global</code> module</a><a
> class="text-reasonml"
> target="_self" href="./api/ml/melange/Js/Global"><code>Js.Global</code>
> module</a><a class="text-reasonml" target="_self"
> href="./api/re/melange/Js/Global"><code>Js.Global</code> module</a>.
Generates:
Expand Down
2 changes: 1 addition & 1 deletion docs/what-is-melange.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ modern JavaScript:
This is a small code component essential for running JavaScript programs
produced by the compiler.

- The [standard libraries](./api.md): Melange includes a set of foundational
- The [standard libraries](./api): Melange includes a set of foundational
elements such as data structures, functions, and bindings to JavaScript APIs,
all aimed at helping developers accelerate app development.

Expand Down

0 comments on commit 300c4f8

Please sign in to comment.