mirror of
https://github.com/apple/pkl.git
synced 2026-06-12 08:34:27 +02:00
Fix incorrect Facts in pkl:base doc comments (#1669)
Several `Facts:` examples in the `pkl:base` standard library docs assert
statements that are false when evaluated. Since these examples are not
run by any test, the mistakes went unnoticed and are rendered verbatim
into the generated API docs, where they mislead readers.
The corrected examples:
- `String.isNotBlank`: `"\t\n\r".isNotBlank` was listed as holding, but
a string of only whitespace is blank, so it is false. Negated it to
match the neighboring `!"".isNotBlank` and `!" ".isNotBlank` examples.
- `DataSize.toBinaryUnit` / `toDecimalUnit`: the `mb`/`mib` lines
mirrored the `kb`/`kib` lines, but the identity only holds for adjacent
units. `1024.kb == 1000.kib` (both 1,024,000 b), whereas `1024.mb` is
1,024,000,000 b and `1000.mib` is 1,048,576,000 b, so they are not
equal. There is no clean round-number equivalent at this magnitude, so I
removed the two false lines; the remaining examples still demonstrate
the conversion.
- `Collection.any`: `!List(1, 2, 3).any((n) -> n.isEven)` is false
because 2 is even. Changed the list to `List(1, 3, 5)` so the negation
holds.
- `IntSeq.end`: the example read `IntSeq(2, 5).start == 5`, which
documents the wrong property and is false (`start` is 2). Corrected it
to `IntSeq(2, 5).end == 5`.
- `List.isDistinctBy` / `distinctBy`: `List("a", "b", "abc")` is not
distinct by length, since `"a"` and `"b"` both have length 1. Switched
to `List("a", "bb", "ccc")` so the distinctness examples hold.
- `Map`: `Map(...).values` returns a `List`, not a `Set`. Corrected the
expected type.
I verified that each corrected example evaluates to `true`, and that the
neighboring examples I kept still pass, using the released Pkl 0.31.1
binary. The changes are confined to doc-comment text, so formatting is
unaffected.
---------
Signed-off-by: Aditya Singh <adisin650@gmail.com>
This commit is contained in:
+2
-2
@@ -889,7 +889,7 @@ alias {
|
||||
```
|
||||
!"".isNotBlank
|
||||
!" ".isNotBlank
|
||||
"\\t\\n\\r".isNotBlank
|
||||
!"\\t\\n\\r".isNotBlank
|
||||
"abc".isNotBlank
|
||||
```
|
||||
"""
|
||||
@@ -1254,7 +1254,7 @@ alias {
|
||||
```
|
||||
!"".isNotBlank
|
||||
!" ".isNotBlank
|
||||
"\\t\\n\\r".isNotBlank
|
||||
!"\\t\\n\\r".isNotBlank
|
||||
"abc".isNotBlank
|
||||
```
|
||||
"""
|
||||
|
||||
+6
-8
@@ -1314,7 +1314,7 @@ external class String extends Any {
|
||||
/// ```
|
||||
/// !"".isNotBlank
|
||||
/// !" ".isNotBlank
|
||||
/// "\t\n\r".isNotBlank
|
||||
/// !"\t\n\r".isNotBlank
|
||||
/// "abc".isNotBlank
|
||||
/// ```
|
||||
@Since { version = "0.31.0" }
|
||||
@@ -1904,7 +1904,6 @@ external class DataSize extends Any {
|
||||
/// Facts:
|
||||
/// ```
|
||||
/// 1024.kb.toBinaryUnit() == 1000.kib
|
||||
/// 1024.mb.toBinaryUnit() == 1000.mib
|
||||
///
|
||||
/// 1000.kib.toBinaryUnit() == 1000.kib
|
||||
/// 1000.b.toBinaryUnit() == 1000.b
|
||||
@@ -1918,7 +1917,6 @@ external class DataSize extends Any {
|
||||
/// Facts:
|
||||
/// ```
|
||||
/// 1000.kib.toDecimalUnit() == 1024.kb
|
||||
/// 1000.mib.toDecimalUnit() == 1024.mb
|
||||
///
|
||||
/// 1000.kb.toDecimalUnit() == 1000.kb
|
||||
/// 1000.b.toDecimalUnit() == 1000.b
|
||||
@@ -2673,7 +2671,7 @@ abstract external class Collection<out Element> extends Any {
|
||||
/// Facts:
|
||||
/// ```
|
||||
/// List(1, 2, 3).any((n) -> n.isEven)
|
||||
/// !List(1, 2, 3).any((n) -> n.isEven)
|
||||
/// !List(1, 3, 5).any((n) -> n.isEven)
|
||||
/// !List().any((n) -> n.isEven)
|
||||
/// ```
|
||||
@AlsoKnownAs { names { "exists" } }
|
||||
@@ -3066,7 +3064,7 @@ external class IntSeq extends Any {
|
||||
///
|
||||
/// Facts:
|
||||
/// ```
|
||||
/// IntSeq(2, 5).start == 5
|
||||
/// IntSeq(2, 5).end == 5
|
||||
/// ```
|
||||
external end: Int
|
||||
|
||||
@@ -3249,7 +3247,7 @@ external class List<out Element> extends Collection<Element> {
|
||||
///
|
||||
/// Facts:
|
||||
/// ```
|
||||
/// List("a", "b", "abc").isDistinctBy((it) -> it.length)
|
||||
/// List("a", "bb", "ccc").isDistinctBy((it) -> it.length)
|
||||
/// !List("a", "ab", "c").isDistinctBy((it) -> it.length)
|
||||
/// ```
|
||||
@AlsoKnownAs { names { "isUniqueBy" } }
|
||||
@@ -3272,7 +3270,7 @@ external class List<out Element> extends Collection<Element> {
|
||||
///
|
||||
/// Facts:
|
||||
/// ```
|
||||
/// List("a", "b", "abc").distinctBy((it) -> it.length) == List("a", "b", "abc")
|
||||
/// List("a", "bb", "ccc").distinctBy((it) -> it.length) == List("a", "bb", "ccc")
|
||||
/// List("a", "ab", "c").distinctBy((it) -> it.length) == List("a", "ab")
|
||||
/// ```
|
||||
@AlsoKnownAs { names { "uniqueBy" } }
|
||||
@@ -3573,7 +3571,7 @@ external class Set<out Element> extends Collection<Element> {
|
||||
/// ```
|
||||
/// Map().isEmpty
|
||||
/// Map("name", "Pigeon", "age", 42).keys == Set("name", "age")
|
||||
/// Map("name", "Pigeon", "age", 42).values == Set("Pigeon", 42)
|
||||
/// Map("name", "Pigeon", "age", 42).values == List("Pigeon", 42)
|
||||
/// ```
|
||||
external const function Map<Key, Value>(keysAndValues: VarArgs<Key | Value>): Map<Key, Value>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user