Doctest stdlib timerelated by spoo · Pull Request #11327 · erlang/otp

spoo · 2026-07-02T21:05:43Z

This PR adds doctest examples to time related modules in Stdlib application for most of the functions

This reverts commit 3c415a9.

This reverts commit 23e5085.

This reverts commit a856f96.

github-actions · 2026-07-02T21:06:31Z

CT Test Results

2 files 100 suites 1h 6m 55s ⏱️
2 306 tests 2 253 ✅ 52 💤 1 ❌
2 728 runs 2 671 ✅ 56 💤 1 ❌

For more details on these failures, see this check.

Results for commit 146a141.

♻️ This comment has been updated with latest results.

To speed up review, make sure that you have read Contributing to Erlang/OTP and that all checks pass.

See the TESTING and DEVELOPMENT HowTo guides for details about how to run test locally.

Artifacts

// Erlang/OTP Github Action Bot

Maria-12648430 · 2026-07-07T15:07:41Z

+2> F = random:uniform(), is_float(F), F > 0.0, F < 1.0.
+true


This results in true for any F that is a number (including integers) that is less than 1.0, for example -5.

Thanks for pointing it . The idea was to demonstrate output as floating and between 0.0 and 1.0. Added 'and' operator now to correct the same than the 'comma' operator. Hope now is ok

Should be andalso.

andalso is generally used for performance when we do not want the second operand to be evaluated, but since here emphasis is on user understanding and documentation i kept it as just "and". Just wondering if really need a change or if this would keep it simpler for user

and and or are deprecated and will raise warnings starting with OTP 29. Effectively, their usage is discouraged. Bringing them up again in documentation examples plainly runs against that. The need for precedence-parentheses that comes with them also makes the examples more confusing. (My 2ct anyway XD).

Maria-12648430 · 2026-07-07T15:08:23Z

+3> I = random:uniform(10), I >= 1, I =< 10.
+true


This results in true for any I that is a number (including floats) that is less than or equal to 10, for example -5.5.

Maria-12648430 · 2026-07-07T15:08:50Z

+2> {Float, _NewState} = random:uniform_s(State), is_float(Float), Float > 0.0, Float < 1.0.
+true


This results in true for any Float that is a number (including integers) that is less than 1.0, for example -5.

Maria-12648430 · 2026-07-07T15:09:44Z

+3> {Int, _NewState2} = random:uniform_s(10, State), Int >= 1, Int =< 10.
+true


This results in true for any Int that is a number (including floats) that is less than or equal to 10, for example -5.5.

Maria-12648430 · 2026-07-07T15:15:36Z

+1> ok = element(1, timer:apply_after(5000, io, format, ["~nHello World!~n", []])).
+ok


This wrapping in element(1, ...) makes the examples pretty confusing. A newcomer will certainly wonder, "Is that needed? What for? 🤔"?

I agree that it makes the example not too clear enough for beginers. I have reverted preexisting examples at start of document back to text script. For newer added examples, since the TRef that is given by apply_after is always dynamic its hard to pattern match output and fails by doctest function in performed by timer_suite module. As per my understanding, examples should pass doctest at anypoint and hence a way verifying they are correct , so here TRef being dynamically generated will not be able to pattern match and hence extracting first element 'ok which will also validate success. I am happy to discuss any other better method that could be adopted otherwise :)

Hm, I don't have much experience with doctests, but as far as I understand the documentation (and by a quick trial), something like...

1> timer:apply_after(5000, io, format, ["~nHello World!~n", []]). {ok, TRef1}

... should work? Or, since you're not using TRef1 subsequently in the example, you could use {ok, _}.

Hm, I don't have much experience with doctests, but as far as I understand the documentation (and by a quick trial), something like...

1> timer:apply_after(5000, io, format, ["~nHello World!~n", []]). {ok, TRef1}

... should work? Or, since you're not using TRef1 subsequently in the example, you could use {ok, _}.

Or...

1> {ok, _} = timer:apply_after(5000, io, format, ["~nHello World!~n", []]).

... and omit the return value if just want to insist on the ok?

if we demonstrate only this one liner without output this works as we completly ignore the TRef which is dynamically generated. Was less aware of this way in doctest.

Maria-12648430 · 2026-07-13T09:02:52Z

+2> {ok, {send_local, Ref1}} = timer:send_after(1000, self(), world), is_reference(Ref1).
+true


The return type of timer:send_after/3 (and friends) is {ok, TRef} (or {error, Reason} for completeness' sake). TRef in turn is of type tref/0, which is an opaque type: you are not supposed to assume anything about what it actually looks like, as you do here with matching on {send_local, Ref1} and later is_reference(Ref1).

juhlig · 2026-07-13T09:17:17Z

-Returns a random float uniformly distributed between `0.0` and `1.0`, updating
-the state in the process dictionary.
-""".
+-doc(#{equiv => uniform(1)}).


This is not correct. As you can see from the spec already, uniform/0 (this function) returns a float(), whereas uniform/1 (the function you declare as equivalent to uniform/0 here) returns a pos_integer().

That is, uniform(1) will always return integer 1, while uniform() will return a float F in the range 0.0 <= F <= 1.0.

juhlig · 2026-07-13T09:23:50Z

+2> F = random:uniform() , is_float(F) and ((F>= 0.0) and (F =< 1.0)).
+true


This does not belong here. As I said in my previous comment, uniform/0 is a different function (which just happens to have the same name).

juhlig · 2026-07-13T09:28:59Z

+3> I = random:uniform(10), ((I >= 1) and (I =< 10)).
+true


I don't think that this is especially enlightening, if anything it makes the example confusing. If you absolutely want to have the "I is an integer 1 =< I =< 10" demonstration in there, you should put it on a different line, like this:

3> I = random:uniform(10). 4> is_integer(I, 1, 10). true

juhlig · 2026-07-13T09:30:40Z

-Returns, for a specified state, a random float uniformly distributed between
-`0.0` and `1.0`, and a new state.
-""".
+-doc(#{equiv => uniform_s(1, State0)}).


Same as with uniform/0/uniform/1, this is not correct.

juhlig · 2026-07-14T10:17:38Z

One of your doctests for calendar is failing. This is not your fault though, the example in question itself is sound. I opened a ticket regarding the underlying issue, #11362.

juhlig · 2026-07-14T11:17:20Z

Looking at your PR in general, you are focusing a lot on testable (vs enlightening) examples. This in turn adds a lot of noise which obfuscates what the examples are actually supposed to demonstrate. IMO, examples in documentation should, first of all, highlight the usage of the function it documents. If the examples can be tested without adding confusing noise, then by all means do so - but if the testability adds confusing noise, don't.

Think about it: there was documentation with imperfect, typo-ridden examples for decades, and people were fine with them nonetheless since it gave them a general idea of how to use something and what happened when. They were rarely used as they were written verbatim.

I guess what I'm trying to say is, there is nothing wrong with debugging examples and making sure that they stay debugged. But making them testable at all costs actually reduces their value for readers.

spoo · 2026-07-15T18:02:44Z

Looking at your PR in general, you are focusing a lot on testable (vs enlightening) examples. This in turn adds a lot of noise which obfuscates what the examples are actually supposed to demonstrate. IMO, examples in documentation should, first of all, highlight the usage of the function it documents. If the examples can be tested without adding confusing noise, then by all means do so - but if the testability adds confusing noise, don't.

Think about it: there was documentation with imperfect, typo-ridden examples for decades, and people were fine with them nonetheless since it gave them a general idea of how to use something and what happened when. They were rarely used as they were written verbatim.

I guess what I'm trying to say is, there is nothing wrong with debugging examples and making sure that they stay debugged. But making them testable at all costs actually reduces their value for readers.

Thanks for feedback . Thinking on same lines, I have now tried to reiterate on some examples that felt like noise , removed emphasis on "testing" (for example (is_tuple(x), or just checking on ok etc) and have tried to rather emphasize on user readability and understanding. Since the doctest idea is that the code examples in module documentation remain guaranteed to stay correct because they are run during testing, have tried to keep in mind that they could be tested as far as possible :).

spoo added 9 commits June 15, 2026 21:46

Added doctest for dets

23e5085

Added few more doctests

a856f96

Added doctest for stdlib error handling modules

3c415a9

Added doctest for time related modules

71b029a

Modification to time related module doctest

8412efe

Revert "Added doctest for stdlib error handling modules"

17d8944

This reverts commit 3c415a9.

Revert "Added doctest for dets"

de3ccfc

This reverts commit 23e5085.

Revert "Added few more doctests"

028f1ae

This reverts commit a856f96.

Modification to time related modules

a5e534b

jhogberg added the team:VM Assigned to OTP team VM label Jul 6, 2026

Maria-12648430 suggested changes Jul 7, 2026

View reviewed changes

Modification to random module on examples

25c69b8

Maria-12648430 reviewed Jul 13, 2026

View reviewed changes

juhlig suggested changes Jul 13, 2026

View reviewed changes

juhlig mentioned this pull request Jul 14, 2026

Erratic behavior of erlang:localtime_to_universaltime/2 #11362

Open

Doctest example modification as per review comments

146a141

		2> {Float, _NewState} = random:uniform_s(State), is_float(Float), Float > 0.0, Float < 1.0.
		true

		3> {Int, _NewState2} = random:uniform_s(10, State), Int >= 1, Int =< 10.
		true

		1> ok = element(1, timer:apply_after(5000, io, format, ["~nHello World!~n", []])).
		ok

		2> {ok, {send_local, Ref1}} = timer:send_after(1000, self(), world), is_reference(Ref1).
		true

		2> F = random:uniform() , is_float(F) and ((F>= 0.0) and (F =< 1.0)).
		true

Uh oh!

Conversation

spoo commented Jul 2, 2026

Uh oh!

github-actions Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CT Test Results

Artifacts

Uh oh!

Choose a reason for hiding this comment

Uh oh!

spoo Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

spoo Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

juhlig Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Maria-12648430 Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

juhlig Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

juhlig commented Jul 14, 2026

Uh oh!

juhlig commented Jul 14, 2026

Uh oh!

spoo commented Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions Bot commented Jul 2, 2026 •

edited

Loading

spoo Jul 10, 2026 •

edited

Loading

spoo Jul 13, 2026 •

edited

Loading

juhlig Jul 14, 2026 •

edited

Loading

Maria-12648430 Jul 13, 2026 •

edited

Loading

juhlig Jul 13, 2026 •

edited

Loading