Skip to content

Fix incorrect Facts in pkl:base doc comments#1615

Closed
adityasingh2400 wants to merge 1 commit into
apple:mainfrom
adityasingh2400:fix-stdlib-doc-facts
Closed

Fix incorrect Facts in pkl:base doc comments#1615
adityasingh2400 wants to merge 1 commit into
apple:mainfrom
adityasingh2400:fix-stdlib-doc-facts

Conversation

@adityasingh2400

Copy link
Copy Markdown
Contributor

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.

Several `Facts:` examples in the standard library documentation assert
statements that are actually false when evaluated. Because these examples
are not executed by any test, the errors went unnoticed and are rendered
verbatim into the generated API docs, where they mislead readers.

The corrected examples are:

- `String.isNotBlank`: `"\t\n\r".isNotBlank` is listed as holding, but a
  string of only whitespace is blank, so the result is false. Negated to
  match the neighboring examples.
- `DataSize.toBinaryUnit`/`toDecimalUnit`: the `mb`/`mib` lines assumed the
  same identity as the `kb`/`kib` lines, but `1024.mb` and `1000.mib` are
  not equal (the unit-factor ratio is squared at this magnitude). Removed
  the two false lines; the remaining examples still demonstrate the method.
- `Collection.any`: `!List(1, 2, 3).any((n) -> n.isEven)` is false because
  2 is even. Changed the list so the negation holds.
- `IntSeq.end`: the example read `IntSeq(2, 5).start == 5`, documenting the
  wrong property. `start` is 2; `end` is 5.
- `List.isDistinctBy`/`distinctBy`: `List("a", "b", "abc")` is not distinct
  by length ("a" and "b" both have length 1). Switched to elements with
  distinct lengths so the examples hold.
- `Map`: `values` returns a `List`, not a `Set`.

Verified each corrected example evaluates to true with Pkl 0.31.1.
@adityasingh2400

Copy link
Copy Markdown
Contributor Author

Withdrawing this one: these are correct but doc-only Facts corrections in the stdlib, which are better handled as a single maintainer-side cleanup than a one-off external PR.

@bioball

bioball commented Jun 8, 2026

Copy link
Copy Markdown
Member

@adityasingh2400 this is a good PR, why don't you re-open this?

@adityasingh2400

Copy link
Copy Markdown
Contributor Author

Thanks @bioball, happy to. I had withdrawn this one thinking it was better as a maintainer-side cleanup, but if you would like it as a PR I am glad to carry it. The fork that backed this branch was deleted in the meantime, so GitHub would not let me reopen #1615 directly. I have restored the exact same change in #1669. No changes beyond what you reviewed here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants