Blocks are not properly introduced in the documentation

[kyegupov]

Blocks and "pipe arguments" syntax is never sufficient explained in the documentation. The section https://crystal-lang.org/docs/syntax_and_semantics/blocks_and_procs.html introduces this syntax matter-of-factly. And even earlier, in https://crystal-lang.org/docs/syntax_and_semantics/literals/proc.html , the "pipe" syntax is being used, despite not having been explained before.

Moreover, the difference between block and procs is never properly explained, despite the name of the section. Why would I want to convert a block to a proc? Why do I have separate "pipe" and "arrow" syntaxes?

This is very confusing for people coming from other languages. The "block" syntax and concept is pretty much unique to Ruby and needs proper explanation.

Compare that to the documentation of the other language that uses "pipe" syntax, note the comprehensiveness and clarity: https://doc.rust-lang.org/1.1.0/book/closures.html

[bew]

@kyegupov What is the "pipe" syntax?

[Sija]

@bew I'd guess it's about block usage variations:

3.times do |i|
  puts i
end

# vs

3.times &->puts(Int32)

[kyegupov]

The pipe syntax is this: |x| something(x)

If you look at the documentation for Crystal, you will discover that this syntax and its meaning is not actually described anywhere.

[bew]

It's not really a pipe syntax, it's the block syntax for passing parameters to the block content:

def foobar
  yield "hello", "world"
end

# Works with normal blocks (using: do ... end}
foobar do |arg1, arg2|
  # this is the block content
  # arg1 & arg2 are the arguments passed to the block
  pp arg1 # => "hello"
  pp arg2 # => "world"
end

# Works also with blocks inline blocks (using: { ... })
only_arg2 = foobar { |arg1, arg2| return arg2 }
pp only_arg2 # => "world"

[kyegupov]

@bew yes, of course. The thing is, the block syntax is NEVER explained in the documentation. I cannot find it properly introduced anywhere.

[asterite]

@kyegupov Writing docs for a language is very hard. Many concepts are tangled. Also said here

You can read this document from top to bottom, but it’s advisable to jump through sections because some concepts are interrelated and can’t be explained in isolation.

[kyegupov]

@asterite I wouldn't have problem with it being explained out of order, but there - just - is - no - explanation - of - what - a - "block" - is, at all. No mention of the | character, no explanation of how argument passing works, no explanation when one needs to chose blocks and when procs.

Writing a good documentation is hard indeed. And that's why I have submitted this issue: to point out a glaring omission in it that needs to be fixed.

[asterite]

It's explained here: https://crystal-lang.org/docs/syntax_and_semantics/blocks_and_procs.html

The idea is to learn from the examples there.

[kyegupov]

That section is very cryptic and can use a lot of improvement, that's precisely my point. Consider this:

The yield expression is similar to a call and can receive arguments.

"similar to a call" - what does that mean? What's the similarity, and where does it end?

"receive arguments" - um, ambiguous, isn't it the block that actually will "receive" the arguments? Anyway, it would be a good place to add something like:

The block indicates the arguments it will accept via the "pipe" characters |. That makes the block similar to a function which does not have a name.

There's the last question (what's the difference between block and procs and why do both exist), but I cannot suggest anything here because I don't understand it myself.

"Learning from examples" is maybe okay for a tutorial. But this is the reference documentation for a language we're talking about. It has to be comprehensive, strict, detailed and unambiguous.

For comparison, please see the Ruby reference documentation on this matter: http://ruby-doc.org/core-2.4.1/doc/syntax/calling_methods_rdoc.html

[mverzilli]

This discussion belongs in the book's repo: crystal-lang/crystal-book#118. Please let's continue there if necessary.