From a9c98e439626ed9619e6244a063fddfc19a74574 Mon Sep 17 00:00:00 2001 From: Aditya Singh <60082699+adityasingh2400@users.noreply.github.com> Date: Thu, 11 Jun 2026 10:10:14 -0700 Subject: [PATCH] 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 --- .../output/api/reflectedDeclaration.pcf | 4 ++-- stdlib/base.pkl | 14 ++++++-------- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/pkl-core/src/test/files/LanguageSnippetTests/output/api/reflectedDeclaration.pcf b/pkl-core/src/test/files/LanguageSnippetTests/output/api/reflectedDeclaration.pcf index 86d541732..176422757 100644 --- a/pkl-core/src/test/files/LanguageSnippetTests/output/api/reflectedDeclaration.pcf +++ b/pkl-core/src/test/files/LanguageSnippetTests/output/api/reflectedDeclaration.pcf @@ -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 ``` """ diff --git a/stdlib/base.pkl b/stdlib/base.pkl index bec7084ba..2b5efaf79 100644 --- a/stdlib/base.pkl +++ b/stdlib/base.pkl @@ -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 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 extends Collection { /// /// 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 extends Collection { /// /// 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 extends Collection { /// ``` /// 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(keysAndValues: VarArgs): Map