Document select keyword

[straight-shoota]

Documentation for the select keyword is missing.

The PR has some details on it: crystal-lang/crystal#3130

[bew]

Also I think there is documentation missing for Channel.select and related functions (I have a nice example of it at https://gist.github.com/bew/9088cf265bd0ea97ddb89dad7926fd3c)

[straight-shoota]

Yeah but that's mostly API documentation, but there would be a good place for this in the concurrency guide as well.

select keyword is somewhat special because it is a language feature that is closely tied to a method from stdlib.

[bew]

Oh yes my bad, didn't saw we were in crystal-book repository.

[straight-shoota]

Related: #279

[ErikAGriffin]

This is still an issue correct? @straight-shoota I couldn't find the select keyword in the reference

[straight-shoota]

Yes, the documentation for select is still missing.
@lbarasti wrote a good introduction at https://lbarasti.com/post/select_statement/

[phil294]

so apparently select is syntax sugar for _select_action according to crystal-lang/crystal#3130, but according to Channel docs https://crystal-lang.org/api/1.4.1/Channel.html all kinds of select methods don't exist? (but they do) How is that possible, I thought the docs were auto-generated from the source?

Usage of Fiber is also hidden, albeit I guess you're supposed to read up on Ruby for that (?)

Then there's also this info gist and lbarasti's article, but nothing official. I find this so confusing - Crystal's docs are overall fantastic, but then there's sometimes these weird gaps in them which force you to read through blog posts and language source. Shouldn't that be top priority, much more than anything currently listed on the Roadmap? Sorry, I'm not complaining, I am just so confused. How do people program in Crystal when its docs are incomplete? ._.

[Blacksmoke16]

How is that possible, I thought the docs were auto-generated from the source?

Reminder that what's auto-generated is the public documentation. It does not include protected/private/nodoced types/methods/etc. In this case they're all :nodoc: because they aren't part of the public API of Channel, but instead an implementation detail of select.

Usage of Fiber is also hidden, albeit I guess you're supposed to read up on Ruby for that (?)

Fiber is deff in the public docs. Is there something specific you're not seeing? https://crystal-lang.org/reference/1.5/guides/concurrency.html is also a good starting point. There should be no need to read Ruby to learn about these topics.

Then there's also this info gist and lbarasti's article, but nothing official. I find this so confusing

Yes, docs can always be improved. Hence why this issue is still open.

[zw963]

How's this thing going?

Even only adding a link is better than not having any documentation on such an important language feature?

[zw963]

A not so perfect doc is FAR FAR better than no doc.

I don't need read this select doc, because i understood it somewhere else.

But, i consider such an important language feature has not been document anywhare for several years. In fact, this is not a difficult task to complete, it is a bit unreasonable!

[zw963]

I think this really not a good things for the Crystal language, the core team probably doesn't have the time to write the docs, and don't hire someone to update the docs, new users can't find the docs, fewer and fewer people are read documentation, and no one is willing to help update the documentation.