Misleading docs about Task.Supervisor function calls.

[maikelthedev]

Elixir and Erlang/OTP versions

So basically in the docs about Task.Supervisor you have this

If they all:

Starts a task that can be awaited on.

then what's the difference between link and nolink. I think the docs should be clearer here on what is the difference of each function.

Current behavior

Docs don't explain what's different.

Expected behavior

Clearer docs explaining the difference of each function

[josevalim]

That line will always be a short summary. Does clicking the function provide more information on what linking is?

[wojtekmach]

My understanding of the issue is explaining the difference between linking and not linking to the caller. Which I think would be out of the scope of these docs. But it wouldn't hurt to link to some documentation that explains the concepts. Perhaps https://hexdocs.pm/elixir/processes.html#links?

[maikelthedev]

That line will always be a short summary. Does clicking the function provide more information on what linking is?

nope. "Linked to the caller" and "not linked to the caller". Sure...but what's LINKED meaning here?

My understanding of the issue is explaining the difference between linking and not linking to the caller.

Yes

Which I think would be out of the scope of these docs. But it wouldn't hurt to link to some documentation that explains the concepts. Perhaps https://hexdocs.pm/elixir/processes.html#links?

Exactly.

For example, if I go into the link with the full function I get what I just wrote above, but no mention of what linking means. As @wojtekmach said, a reference to it would be awesome. I have some handle_info stuff being triggered in a LiveView out of some task called inside a supervisor and without a full explainer of what linking or not linking is, I couldn't figure it out.

LiveView calls a genserver (client) who calls a Task.Supervisor.async_no_link(something) but somehow when the task running inside there finishes the result is sent to a handle_info in the Liveview (no idea why). I fixed it with Task.Supervisor.start_child but I've got no idea why that fixed it nor why was the liveview called.

Docs are normally very clear with this things, but here is a rabbit hole, they send you to .async, async explains again nothing about linking.

[maikelthedev]

So it is just as matter really of adding a link to what @wojtekmach supplied. Meaning this: https://hexdocs.pm/elixir/processes.html#links

[pejrich]

That line will always be a short summary. Does clicking the function provide more information on what linking is?

nope. "Linked to the caller" and "not linked to the caller". Sure...but what's LINKED meaning here?

Here's an Erlang link about links, and one from the Elixir docs but overall I actually think the docs are doing what they're supposed to be doing here. Documentation is not a tutorial to learn the language, but rather a reference for things which you may know of, but forget the specifics. The more basic information that's put in the docs, the less useful they become once you're comfortable with the language. Learning about linking is typically a one time thing, but referencing what arguments or options a function takes is something even after years with the language I still do on a daily basis. Obviously if you have to wade through a 101 of every topic just to find what options a function takes, it gets pretty cumbersome. I think Elixir does a stellar job at providing really helpful docs, both to those who haven't used a particular function before, and to those who have used it many times but want to check up on some specifics details. But generally if documentation is missing features/functionality of that function, I agree it could be updated. But in this case fixing it as you suggest would require putting information that's really not related to this function at all. Sure, this function has a linking and non-linking version, but those are concepts used broadly in the language, and certainly each specific function that links or doesn't link can't be expected to explain what linking is. After all to explain linking you'd need to mention processes, should this particular function's docs explain how processes work? Obviously not. Think of it like a recipe. An omlet recipe is not a great place to learn about what eggs are. It's a great place to find a new way to use eggs, or to find specific measurements if you forgot them.

[josevalim]

The docs say:

The task will still be linked to the caller, see Task.async/3 for more information

The mistake is that Task.async/1 is the one with more information and it contains a whole section on linking. I will fix that and we should be good. Ty.

[maikelthedev]

Wonderful, thank you @josevalim 😁