Proc definition might be confusing

[vlazar]

I've been reading book sequentially and stumbled upon this https://crystal-lang.org/reference/syntax_and_semantics/literals/proc.html

A Proc represents a function pointer with an optional context (the closure data). It is typically created with a proc literal:

So proc is defined as function pointer with optional closure data. Looks like these 3 concepts (potentially unknown to a reader) were not explained before. This can be very confusing.

Also the function is not even a concept in Crystal except for in C bindings, or is it? At least it does not seem it has a separate page with explanations.

[straight-shoota]

Function pointer and closure are general technical terms, not specific to Crystal. I suppose the language reference shouldn't have to define every potentially unknown concept to the reader. Maybe we could add a link to https://en.wikipedia.org/wiki/Function_pointer for convenience?

Crystal has functions as well, but it's not a popular concept and mainly here for C interop. And apparently function definitions are missing from the reference. The fun keyword is only explained for binding library functions in lib contexts. But it can also be used to define a function in Crystal itself, which happens to work similar to a method:

fun foo
  puts "foo"
end

foo

It's only useful for low-level stuff, though. But it should be documented.

[vlazar]

Linking to definitions would be nice I think. I am reading reference using Next button and sometimes some concepts are being mentioned without some prior explanation or any references like links to a separate page. For example Assignment section is placed before Variables and shows.. well assignment to things that are not explained yet (variables). I know it's hard and not always possible to have everything defined in strict sequence, so references would help.

In this case I felt like the sentence was to complex with many new terms (new as in first time mentioned in reference, not to me or someone else who might be familiar with then in other languages).

I've noticed function and was seeing it for the first time since I've started reading reference. I've searched the reference and it showed me not much results. So at this point it might be not very clear if function is something that one could (or should) use in normal Crystal code, or is it just reserved for C libs, or is it just a way to describe procs.

Not sure if that would be even correct, but since you can create a proc from method would something like this be also correct way to describe a proc?

A Proc is a reference to a method with an optional context (the closure data). It is typically created with a proc literal.

We still have reference and closure but at least method is more common than 'functionin Crystal. Links to something not mentioned before in the book likereferenceandclosure` could help a lot I think.

[straight-shoota]

It is really great feedback. Why don't you directly edit the content while reading when you encounter something that could be improved? If you don't know a better solution immediately, just place a comment. Then turn that into a PR (or multiple ones, step by step) and we can talk more focused on the individual issues.

In general, as you already mentioned, the reference can hardly be fully sequential. But we sure can add references to sections that follow later.

[vlazar]

On the related note I've tried to define a function in a class and got this message:

Error: can only declare fun at lib or global scope

Should that be expanded to at least say function and not fun? 😆 Or rephrase it maybe? Something like:

Error: fun can only be used at lib or global scope

[vlazar]

It is really great feedback. Why don't you directly edit the content while reading when you encounter something that could be improved? If you don't know a better solution immediately, just place a comment. Then turn that into a PR (or multiple ones, step by step) and we can talk more focused on the individual issues.

Honestly I wasn't sure what is a good or recommended process for this.

I started to read book and I definitely want to share my feedback if you find it useful. I haven't read any Crystal docs for a while, so now I'm kinda newcomer and it's a perfect time for me to notice and share anything I find surprising.

Using a pencil icon and opening a separate PR for each thing that bothers me doesn't feel scalable.

So I've opened an issue for this one. I guess that also does not scale well.

I think if something like comments in Google Docs could be added to a book, maybe even with voting, that could help a lot by simplifying focused conversations.

[straight-shoota]

I'd just check out the repository locally and add edits/comments to the respective source files while reading the rendered web version. You can also build and serve manually (make serve - needs python installed) to preview your edits.

[vlazar]

Sure, I can check out repo and do some changes as I go, but I think the more edits I make the less likely my PR would not be accepted, right? Unless it's small and focused on a single thing.

[straight-shoota]

I'd mostly see the PR as a basis for discussion. We can split it in smaller bites if necessary.