Rewrite SpecialForms doc examples as doctests #14435

dmitrykleymenov · 2025-04-13T06:28:54Z

Rewrote some code snippets to remove side effects and compiler warnings. Also added a couple of tests and made them more consistent in try/1

josevalim · 2025-04-14T15:12:17Z

lib/elixir/lib/kernel/special_forms.ex

-      rescue
-        UndefinedFunctionError -> nil
-      end
+  Rescue a single exception without binding the exception to a variable


Suggested change

Rescue a single exception without binding the exception to a variable

Rescue a single exception without binding the exception to a variable:

josevalim · 2025-04-14T15:12:27Z

lib/elixir/lib/kernel/special_forms.ex

-      rescue
-        x in [UndefinedFunctionError] -> nil
-      end
+  Rescue any of the given exception without binding


Suggested change

Rescue any of the given exception without binding

Rescue any of the given exception without binding:

josevalim · 2025-04-14T15:12:36Z

lib/elixir/lib/kernel/special_forms.ex

+      ...> end
+      :rescued
+
+  Rescue and bind the exception to the variable "x"


Suggested change

Rescue and bind the exception to the variable "x"

Rescue and bind the exception to the variable "x":

For consistency with your other comment, do you mean:

Suggested change

Rescue and bind the exception to the variable "x"

Rescue and bind the exception to the variable `x`:

josevalim · 2025-04-14T15:13:11Z

lib/elixir/lib/kernel/special_forms.ex

+      ...> end
+      [:rescued, true]
+
+  Rescue several errors differently


Suggested change

Rescue several errors differently

Rescue different errors with separate clauses:

josevalim · 2025-04-14T15:13:19Z

lib/elixir/lib/kernel/special_forms.ex

+      :rescued_arithmetic_error
+
+  Rescue all kinds of exceptions and bind the rescued exception
+  to the variable "x"


Suggested change

to the variable "x"

to the variable `x`:

josevalim · 2025-04-14T15:14:14Z

lib/elixir/lib/kernel/special_forms.ex

+      iex> try do
+      ...>   :returned
+      ...> after
+      ...>   send(self(), :send_from_after_block)


I am not sure I like this new version, it requires the user to understand message passing in order to grasp it, while IO.puts is more "natural".

It prints the message to stdout along with dots from passing tests(for now there are only dots). Is it ok to have messages there or should it be reverted to plain code? My point was to minimize side effects, but since after block never returns a value, it's hard to show the block call without side effects

Do you have an opinion, @sabiwara?

And one more thing: I'm not sure but think try/1 is more or less an advanced feature, so highly likely a reader knows about message passing in general. Even without this knowledge, send, self, and receive are maximum self-descriptive. Just thoughts

@josevalim I agree that it looks more natural and much simpler.
Since by definition after is about side effects, and IO.puts is the simplest example, I think it makes sense not to have a doctest at all cost here?

Every other idea I come up with is more advanced and/or weird/non-idiomatic: process dict, agent, ETS ...
The only one that doesn't feel too bad and illustrates a typical use of after could be: create a tmp file and clean it up in after? But that's not something we typically do in doctests perhaps.

And one more thing: I'm not sure but think try/1 is more or less an advanced feature, so highly likely a reader knows about message passing in general. Even without this knowledge, send, self, and receive are maximum self-descriptive. Just thoughts

I don't think that's necessarily true though - especially for people with experience in other languages, who would typically be aware of try/finally / defer constructs but might still not know much about message passing.

I don't think that's necessarily true though - especially for people with experience in other languages, who would typically be aware of try/finally / defer constructs but might still not know much about message passing.

Thank you for your feedback, you are right. So, revert to plain code or tmp file

Plain code :)

josevalim

One comment about message passing and we are good to go!

sabiwara · 2025-04-14T22:23:31Z

lib/elixir/lib/kernel/special_forms.ex

+      ...> end
+      :rescued
+
+  Rescue and bind the exception to the variable "x"


For consistency with your other comment, do you mean:

Suggested change

Rescue and bind the exception to the variable "x"

Rescue and bind the exception to the variable `x`:

sabiwara · 2025-04-14T22:42:11Z

lib/elixir/lib/kernel/special_forms.ex

+      iex> try do
+      ...>   :returned
+      ...> after
+      ...>   send(self(), :send_from_after_block)


@josevalim I agree that it looks more natural and much simpler.
Since by definition after is about side effects, and IO.puts is the simplest example, I think it makes sense not to have a doctest at all cost here?

Every other idea I come up with is more advanced and/or weird/non-idiomatic: process dict, agent, ETS ...
The only one that doesn't feel too bad and illustrates a typical use of after could be: create a tmp file and clean it up in after? But that's not something we typically do in doctests perhaps.

And one more thing: I'm not sure but think try/1 is more or less an advanced feature, so highly likely a reader knows about message passing in general. Even without this knowledge, send, self, and receive are maximum self-descriptive. Just thoughts

I don't think that's necessarily true though - especially for people with experience in other languages, who would typically be aware of try/finally / defer constructs but might still not know much about message passing.

sabiwara · 2025-04-14T22:45:50Z

lib/elixir/lib/kernel/special_forms.ex

+      ...>     IO.puts(:stderr, "Unexpected message received")
+      ...> after
+      ...>   10 ->
+      ...>     "return this after 10 milliseconds"


I think the original message was nicer to explain?

Suggested change

...> "return this after 10 milliseconds"

...> "No message in 10 milliseconds"

lib/elixir/lib/kernel/special_forms.ex

sabiwara

LGTM except the one comment.
Thanks @dmitrykleymenov ! 💜

Fix doctest typo for `try/2` Co-authored-by: Jean Klingler <[email protected]>

dmitrykleymenov added 4 commits April 12, 2025 10:06

Change code snippets from texts to doctests for cond/1

5e3901f

Add doctests to try/1

e9c9da0

Add doctests to receive/1

7619a72

Doc style fixes

ec99f73

josevalim reviewed Apr 14, 2025

View reviewed changes

sabiwara reviewed Apr 14, 2025

View reviewed changes

Return try/1doctests with after block to plain code

20d420d

josevalim approved these changes Apr 15, 2025

View reviewed changes

sabiwara reviewed Apr 25, 2025

View reviewed changes

lib/elixir/lib/kernel/special_forms.ex Outdated Show resolved Hide resolved

sabiwara approved these changes Apr 25, 2025

View reviewed changes

Update lib/elixir/lib/kernel/special_forms.ex

a58526f

Fix doctest typo for `try/2` Co-authored-by: Jean Klingler <[email protected]>

sabiwara changed the title ~~Special forms doctests~~ Rewrite SpecialForms doc examples as doctests Apr 25, 2025

sabiwara merged commit 075b8ca into elixir-lang:main Apr 25, 2025
11 checks passed

	Rescue a single exception without binding the exception to a variable
	Rescue a single exception without binding the exception to a variable:

	Rescue any of the given exception without binding
	Rescue any of the given exception without binding:

	Rescue and bind the exception to the variable "x"
	Rescue and bind the exception to the variable "x":

	Rescue several errors differently
	Rescue different errors with separate clauses:

	...> "return this after 10 milliseconds"
	...> "No message in 10 milliseconds"

Rewrite SpecialForms doc examples as doctests #14435

Rewrite SpecialForms doc examples as doctests #14435

Uh oh!

Conversation

dmitrykleymenov commented Apr 13, 2025

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!

dmitrykleymenov Apr 14, 2025 • 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!

dmitrykleymenov Apr 14, 2025 • 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!

dmitrykleymenov Apr 15, 2025 • 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!

josevalim left a comment

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!

Uh oh!

sabiwara left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

dmitrykleymenov Apr 14, 2025 •

edited

Loading

dmitrykleymenov Apr 14, 2025 •

edited

Loading

dmitrykleymenov Apr 15, 2025 •

edited

Loading