Skip to content

Commit 176d127

Browse files
aspeddroaspeddro
committed
update docstrings
1 parent 165aba1 commit 176d127

File tree

5 files changed

+127
-69
lines changed

5 files changed

+127
-69
lines changed

‎data/api/latest/belt.json

Lines changed: 53 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -369,7 +369,8 @@
369369
"id": "Belt.HashSet.String",
370370
"name": "String",
371371
"docstrings": [
372-
"Specalized when key type is `string`, more efficient than the generic type"
372+
"Specalized when key type is `string`, more efficient than the generic type",
373+
"This module is [`Belt.HashSet`]() specialized with key type to be a primitive type.\n\nIt is more efficient in general, the API is the same with [`Belt.HashSet`]() except its key type is fixed,\nand identity is not needed(using the built-in one)\n\n**See** [`Belt.HashSet`]()"
373374
],
374375
"items": [
375376
{
@@ -511,7 +512,8 @@
511512
"id": "Belt.HashSet.Int",
512513
"name": "Int",
513514
"docstrings": [
514-
"Specalized when key type is `int`, more efficient than the generic type"
515+
"Specalized when key type is `int`, more efficient than the generic type",
516+
"This module is [`Belt.HashSet`]() specialized with key type to be a primitive type.\n\nIt is more efficient in general, the API is the same with [`Belt.HashSet`]() except its key type is fixed,\nand identity is not needed(using the built-in one)\n\n**See** [`Belt.HashSet`]()"
515517
],
516518
"items": [
517519
{
@@ -1359,7 +1361,8 @@
13591361
"id": "Belt.MutableSet.String",
13601362
"name": "String",
13611363
"docstrings": [
1362-
"Specialized when key type is `string`, more efficient than the generic type"
1364+
"Specialized when key type is `string`, more efficient than the generic type",
1365+
"This module is [`Belt.MutableSet`]() specialized with key type to be a primitive type.\n\nIt is more efficient in general, the API is the same with [`Belt.MutableSet`]() except its key type is fixed,\nand identity is not needed(using the built-in one)\n\n**See** [`Belt.MutableSet`]()"
13631366
],
13641367
"items": [
13651368
{
@@ -1700,7 +1703,8 @@
17001703
"id": "Belt.MutableSet.Int",
17011704
"name": "Int",
17021705
"docstrings": [
1703-
"Specialized when key type is `int`, more efficient than the generic type"
1706+
"Specialized when key type is `int`, more efficient than the generic type",
1707+
"This module is [`Belt.MutableSet`]() specialized with key type to be a primitive type.\n\nIt is more efficient in general, the API is the same with [`Belt.MutableSet`]() except its key type is fixed,\nand identity is not needed(using the built-in one)\n\n**See** [`Belt.MutableSet`]()"
17041708
],
17051709
"items": [
17061710
{
@@ -2040,7 +2044,9 @@
20402044
"belt/map/dict": {
20412045
"id": "Belt.Map.Dict",
20422046
"name": "Dict",
2043-
"docstrings": [],
2047+
"docstrings": [
2048+
"This module separates identity from data, it is a bit more verbose but\nslightly more efficient due to the fact that there is no need to pack\nidentity and data back after each operation.\n\n**_Advanced usage only_**"
2049+
],
20442050
"items": [
20452051
{
20462052
"id": "Belt.Map.Dict.t",
@@ -3311,7 +3317,8 @@
33113317
"id": "Belt.Set.Dict",
33123318
"name": "Dict",
33133319
"docstrings": [
3314-
"This module separates identity from data, it is a bit more verbose but slightly\nmore efficient due to the fact that there is no need to pack identity and data back\nafter each operation"
3320+
"This module separates identity from data, it is a bit more verbose but slightly\nmore efficient due to the fact that there is no need to pack identity and data back\nafter each operation",
3321+
"This module separates identity from data. It is a bit more verbose but slightly\nmore efficient due to the fact that there is no need to pack identity and data\nback after each operation."
33153322
],
33163323
"items": [
33173324
{
@@ -3679,7 +3686,8 @@
36793686
"id": "Belt.Set.String",
36803687
"name": "String",
36813688
"docstrings": [
3682-
"Specialized when value type is `string`, more efficient than the generic type,\nits compare behavior is fixed using the built-in comparison"
3689+
"Specialized when value type is `string`, more efficient than the generic type,\nits compare behavior is fixed using the built-in comparison",
3690+
"This module is [`Belt.Set`]() specialized with value type to be a primitive type.\nIt is more efficient in general, the API is the same with [`Belt_Set`]() except its value type is fixed,\nand identity is not needed(using the built-in one)\n\n**See** [`Belt.Set`]()"
36833691
],
36843692
"items": [
36853693
{
@@ -4007,7 +4015,8 @@
40074015
"id": "Belt.Set.Int",
40084016
"name": "Int",
40094017
"docstrings": [
4010-
"Specialized when value type is `int`, more efficient than the generic type, its\ncompare behavior is fixed using the built-in comparison"
4018+
"Specialized when value type is `int`, more efficient than the generic type, its\ncompare behavior is fixed using the built-in comparison",
4019+
"This module is [`Belt.Set`]() specialized with value type to be a primitive type.\nIt is more efficient in general, the API is the same with [`Belt_Set`]() except its value type is fixed,\nand identity is not needed(using the built-in one)\n\n**See** [`Belt.Set`]()"
40114020
],
40124021
"items": [
40134022
{
@@ -4335,7 +4344,8 @@
43354344
"id": "Belt.SortArray.String",
43364345
"name": "String",
43374346
"docstrings": [
4338-
"Specalized when key type is `string`, more efficient than the generic type"
4347+
"Specalized when key type is `string`, more efficient than the generic type",
4348+
"This is a specialized module for [`Belt_SortArray`](), the docs in that module also\napplies here, except the comparator is fixed and inlined"
43394349
],
43404350
"items": [
43414351
{
@@ -4419,7 +4429,8 @@
44194429
"id": "Belt.SortArray.Int",
44204430
"name": "Int",
44214431
"docstrings": [
4422-
"Specalized when key type is `int`, more efficient than the generic type"
4432+
"Specalized when key type is `int`, more efficient than the generic type",
4433+
"This is a specialized module for [`Belt_SortArray`](), the docs in that module also\napplies here, except the comparator is fixed and inlined"
44234434
],
44244435
"items": [
44254436
{
@@ -4629,7 +4640,8 @@
46294640
"id": "Belt.Float",
46304641
"name": "Float",
46314642
"docstrings": [
4632-
"[`Belt.Float`]()\n\n Utilities for Float."
4643+
"[`Belt.Float`]()\n\n Utilities for Float.",
4644+
"This module includes convenience methods for handling `float` types."
46334645
],
46344646
"items": [
46354647
{
@@ -4710,7 +4722,8 @@
47104722
"id": "Belt.Int",
47114723
"name": "Int",
47124724
"docstrings": [
4713-
"[`Belt.Int`]()\n\n Utilities for Int."
4725+
"[`Belt.Int`]()\n\n Utilities for Int.",
4726+
"This module includes convenience methods for handling `int` types."
47144727
],
47154728
"items": [
47164729
{
@@ -4791,7 +4804,8 @@
47914804
"id": "Belt.Result",
47924805
"name": "Result",
47934806
"docstrings": [
4794-
"[`Belt.Result`]()\n\n Utilities for result data type."
4807+
"[`Belt.Result`]()\n\n Utilities for result data type.",
4808+
"Result types are really useful to describe the result of a certain operation\nwithout relying on exceptions or `option` types.\n\nThis module gives you useful utilities to create and combine `Result` data."
47954809
],
47964810
"items": [
47974811
{
@@ -4923,7 +4937,8 @@
49234937
"id": "Belt.Option",
49244938
"name": "Option",
49254939
"docstrings": [
4926-
"[`Belt.Option`]()\n\n Utilities for option data type."
4940+
"[`Belt.Option`]()\n\n Utilities for option data type.",
4941+
"In Belt we represent the existence and nonexistence of a value by wrapping it\nwith the `option` type. In order to make it a bit more convenient to work with\noption-types, Belt provides utility-functions for it.\n\nThe `option` type is a part of the ReScript standard library which is defined like this:\n\n## Examples\n\n```rescript\ntype option<'a> = None | Some('a)\n```\n\n```rescript\nlet someString: option<string> = Some(\"hello\")\n```"
49274942
],
49284943
"items": [
49294944
{
@@ -5112,7 +5127,8 @@
51125127
"id": "Belt.HashMap",
51135128
"name": "HashMap",
51145129
"docstrings": [
5115-
"[`Belt.HashMap`]()\n\n The top level provides generic **mutable** hash map operations.\n\n It also has two specialized inner modules\n [`Belt.HashMap.Int`]() and [`Belt.HashMap.String`]()"
5130+
"[`Belt.HashMap`]()\n\n The top level provides generic **mutable** hash map operations.\n\n It also has two specialized inner modules\n [`Belt.HashMap.Int`]() and [`Belt.HashMap.String`]()",
5131+
"A **mutable** Hash map which allows customized [`hash`]() behavior.\n\nAll data are parameterized by not its only type but also a unique identity in\nthe time of initialization, so that two _HashMaps of ints_ initialized with different\n_hash_ functions will have different type.\n\n## Examples\n\n```rescript\ntype t = int\nmodule I0 = unpack(Belt.Id.hashableU(~hash=(. a: t) => \"&\"(a, 0xff_ff), ~eq=(. a, b) => a == b))\nlet s0: t<_, string, _> = make(~hintSize=40, ~id=module(I0))\n\nmodule I1 = unpack(Belt.Id.hashableU(~hash=(. a: t) => \"&\"(a, 0xff), ~eq=(. a, b) => a == b))\nlet s1: t<_, string, _> = make(~hintSize=40, ~id=module(I1))\n```\n\nThe invariant must be held: for two elements who are _equal_,\ntheir hashed value should be the same\n\nHere the compiler would infer `s0` and `s1` having different type so that\nit would not mix.\n\n## Examples\n\n```rescript\nlet s0: t<int, I0.identity>\nlet s1: t<int, I1.identity>\n```\n\nWe can add elements to the collection:\n\n## Examples\n\n```rescript\nlet () = {\n add(s1, 0, \"3\")\n add(s1, 1, \"3\")\n}\n```\n\nSince this is an mutable data strucure, `s1` will contain two pairs."
51165132
],
51175133
"items": [
51185134
{
@@ -5335,7 +5351,8 @@
53355351
"id": "Belt.HashSet",
53365352
"name": "HashSet",
53375353
"docstrings": [
5338-
"[`Belt.HashSet`]()\n\n The top level provides generic **mutable** hash set operations.\n\n It also has two specialized inner modules\n [`Belt.HashSet.Int`]() and [`Belt.HashSet.String`]()"
5354+
"[`Belt.HashSet`]()\n\n The top level provides generic **mutable** hash set operations.\n\n It also has two specialized inner modules\n [`Belt.HashSet.Int`]() and [`Belt.HashSet.String`]()",
5355+
"A **mutable** Hash set which allows customized `hash` behavior.\n\nAll data are parameterized by not its only type but also a unique identity in\nthe time of initialization, so that two _HashSets of ints_ initialized with\ndifferent _hash_ functions will have different type.\n\n## Examples\n\n```rescript\nmodule I0 = unpack(\n Belt.Id.hashableU(\n ~hash=(. a: int) => land(a, 65535),\n ~eq=(. a, b) => a == b,\n )\n)\n\nlet s0 = Belt.HashSet.make(~id=module(I0), ~hintSize=40)\n\nmodule I1 = unpack(\n Belt.Id.hashableU(\n ~hash=(. a: int) => land(a, 255),\n ~eq=(. a, b) => a == b,\n )\n)\n\nlet s1 = Belt.HashSet.make(~id=module(I1), ~hintSize=40)\n\nBelt.HashSet.add(s1, 0)\nBelt.HashSet.add(s1, 1)\n```\n\nThe invariant must be held: for two elements who are equal, their hashed\nvalue should be the same.\n\nHere the compiler would infer `s0` and `s1` having different type so that it\nwould not mix.\n\n## Examples\n\n```rescript\nlet s0: Belt.HashSet.t<int, I0.identity>\nlet s1: Belt.HashSet.t<int, I1.identity>\n```\n\nWe can add elements to the collection (see last two lines in the example\nabove). Since this is an mutable data structure, `s1` will contain two pairs."
53395356
],
53405357
"items": [
53415358
{
@@ -5843,7 +5860,8 @@
58435860
"id": "Belt.MutableSet",
58445861
"name": "MutableSet",
58455862
"docstrings": [
5846-
"[`Belt.MutableSet`]()\n\n The top level provides generic **mutable** set operations.\n\n It also has two specialized inner modules\n [`Belt.MutableSet.Int`]() and [`Belt.MutableSet.String`]()"
5863+
"[`Belt.MutableSet`]()\n\n The top level provides generic **mutable** set operations.\n\n It also has two specialized inner modules\n [`Belt.MutableSet.Int`]() and [`Belt.MutableSet.String`]()",
5864+
"A **mutable** sorted set module which allows customized compare behavior.\nThe implementation uses balanced binary trees, and therefore searching and insertion take time logarithmic in the size of the map.\n\nIt also has two specialized inner modules [Belt.MutableSet.Int](mutable-set-int) and [Belt.MutableSet.String](mutable-set-string) - This module separates data from function which is more verbose but slightly more efficient\n\n## Examples\n\n```rescript\nmodule PairComparator = Belt.Id.MakeComparable({\n type t = (int, int)\n let cmp = ((a0, a1), (b0, b1)) =>\n switch Pervasives.compare(a0, b0) {\n | 0 => Pervasives.compare(a1, b1)\n | c => c\n }\n})\n\nlet mySet = Belt.MutableSet.make(~id=module(PairComparator))\nmySet->Belt.MutableSet.add((1, 2))\n```"
58475865
],
58485866
"items": [
58495867
{
@@ -6234,7 +6252,8 @@
62346252
"id": "Belt.Map",
62356253
"name": "Map",
62366254
"docstrings": [
6237-
"[`Belt.Map`](),\n\n The top level provides generic **immutable** map operations.\n\n It also has three specialized inner modules\n [`Belt.Map.Int`](), [`Belt.Map.String`]() and\n\n [`Belt.Map.Dict`](): This module separates data from function\n which is more verbose but slightly more efficient"
6255+
"[`Belt.Map`](),\n\n The top level provides generic **immutable** map operations.\n\n It also has three specialized inner modules\n [`Belt.Map.Int`](), [`Belt.Map.String`]() and\n\n [`Belt.Map.Dict`](): This module separates data from function\n which is more verbose but slightly more efficient",
6256+
"The top level provides generic immutable map operations.\n\nIt also has three specialized inner modules `Belt.Map.Int`, `Belt.Map.String`\nand `Belt.Map.Dict`."
62386257
],
62396258
"items": [
62406259
{
@@ -6739,7 +6758,8 @@
67396758
"id": "Belt.Set",
67406759
"name": "Set",
67416760
"docstrings": [
6742-
"[`Belt.Set`]()\n\n The top level provides generic **immutable** set operations.\n\n It also has three specialized inner modules\n [`Belt.Set.Int`](), [`Belt.Set.String`]() and\n\n [`Belt.Set.Dict`](): This module separates data from function\n which is more verbose but slightly more efficient"
6761+
"[`Belt.Set`]()\n\n The top level provides generic **immutable** set operations.\n\n It also has three specialized inner modules\n [`Belt.Set.Int`](), [`Belt.Set.String`]() and\n\n [`Belt.Set.Dict`](): This module separates data from function\n which is more verbose but slightly more efficient",
6762+
"An _immutable_ sorted set module which allows customized _compare_ behavior.\n\nThe implementation uses balanced binary trees, and therefore searching\nand insertion take time logarithmic in the size of the map.\n\nFor more info on this module's usage of identity, `make` and others, please see\nthe top level documentation of Belt, **A special encoding for collection safety**.\n\n## Examples\n\n```rescript\nmodule PairComparator =\n Belt.Id.MakeComparable({\n type t = (int, int)\n let cmp = ((a0, a1), (b0, b1)) =>\n switch (Pervasives.compare(a0, b0)) {\n | 0 => Pervasives.compare(a1, b1)\n | c => c\n }\n })\n\nlet mySet = Belt.Set.make(~id=module(PairComparator))\nlet mySet2 = Belt.Set.add(mySet, (1, 2))\n```\n\n**Note:** This module's examples will assume a predeclared module for integers\ncalled `IntCmp`. It is declared like this:\n\n```rescript\nmodule IntCmp =\n Belt.Id.MakeComparable({\n type t = int\n let cmp = Pervasives.compare\n })\n```"
67436763
],
67446764
"items": [
67456765
{
@@ -7134,7 +7154,8 @@
71347154
"id": "Belt.Range",
71357155
"name": "Range",
71367156
"docstrings": [
7137-
"[`Belt.Range`]()\n\n Utilities for a closed range `(from, start)`"
7157+
"[`Belt.Range`]()\n\n Utilities for a closed range `(from, start)`",
7158+
"A small utility module to provide inclusive range operations for `[start, finish]`.\nInternally it is relying on loops instead of creating new arrays, which makes it\npretty performant and memory friendly."
71387159
],
71397160
"items": [
71407161
{
@@ -7223,7 +7244,8 @@
72237244
"id": "Belt.List",
72247245
"name": "List",
72257246
"docstrings": [
7226-
"[`Belt.List`]()\n\n Utilities for List data type"
7247+
"[`Belt.List`]()\n\n Utilities for List data type",
7248+
"Collection functions for manipulating the `list` data structures, a singly-linked list.\n\n**Prefer Array** if you need any of the following:\n\n- Random access of element\n- Better interop with JavaScript\n- Better memory usage & performance."
72277249
],
72287250
"items": [
72297251
{
@@ -8035,7 +8057,8 @@
80358057
"id": "Belt.MutableStack",
80368058
"name": "MutableStack",
80378059
"docstrings": [
8038-
"[`Belt.MutableStack`]()\n\n An FILO(first in last out) stack data structure"
8060+
"[`Belt.MutableStack`]()\n\n An FILO(first in last out) stack data structure",
8061+
"First in last out stack. This module implements stacks, with in-place\nmodification."
80398062
],
80408063
"items": [
80418064
{
@@ -8157,7 +8180,8 @@
81578180
"id": "Belt.MutableQueue",
81588181
"name": "MutableQueue",
81598182
"docstrings": [
8160-
"[`Belt.MutableQueue`]()\n\n An FIFO(first in first out) queue data structure"
8183+
"[`Belt.MutableQueue`]()\n\n An FIFO(first in first out) queue data structure",
8184+
"A FIFO (first in first out) queue data structure."
81618185
],
81628186
"items": [
81638187
{
@@ -8356,7 +8380,8 @@
83568380
"id": "Belt.SortArray",
83578381
"name": "SortArray",
83588382
"docstrings": [
8359-
"[`Belt.SortArray`]()\n\n The top level provides some generic sort related utilities.\n\n It also has two specialized inner modules\n [`Belt.SortArray.Int`]() and [`Belt.SortArray.String`]()"
8383+
"[`Belt.SortArray`]()\n\n The top level provides some generic sort related utilities.\n\n It also has two specialized inner modules\n [`Belt.SortArray.Int`]() and [`Belt.SortArray.String`]()",
8384+
"A module for Array sort relevant utiliites"
83608385
],
83618386
"items": [
83628387
{
@@ -8489,7 +8514,8 @@
84898514
"id": "Belt.Array",
84908515
"name": "Array",
84918516
"docstrings": [
8492-
"[`Belt.Array`]()\n\n **mutable array**: Utilities functions"
8517+
"[`Belt.Array`]()\n\n **mutable array**: Utilities functions",
8518+
"Utililites for `Array` functions.\n\n### Note about index syntax\n\nCode like `arr[0]` does *not* compile to JavaScript `arr[0]`. Reason transforms\nthe `[]` index syntax into a function: `Array.get(arr, 0)`. By default, this\nuses the default standard library's `Array.get` function, which may raise an\nexception if the index isn't found. If you `open Belt`, it will use the\n`Belt.Array.get` function which returns options instead of raising exceptions. \n[See this for more information](../belt.mdx#array-access-runtime-safety)."
84938519
],
84948520
"items": [
84958521
{
@@ -9187,7 +9213,8 @@
91879213
"id": "Belt.Id",
91889214
"name": "Id",
91899215
"docstrings": [
9190-
"[`Belt.Id`]()\n\n Provide utilities to create identified comparators or hashes for\n data structures used below.\n\n It create a unique identifier per module of\n functions so that different data structures with slightly different\n comparison functions won't mix"
9216+
"[`Belt.Id`]()\n\n Provide utilities to create identified comparators or hashes for\n data structures used below.\n\n It create a unique identifier per module of\n functions so that different data structures with slightly different\n comparison functions won't mix",
9217+
"[`Belt.Id`]()\n\nProvide utiliites to create identified comparators or hashes for\ndata structures used below.\n\nIt create a unique identifer per module of functions so that different data structures with slightly different\ncomparison functions won't mix."
91919218
],
91929219
"items": [
91939220
{

0 commit comments

Comments
 (0)