Add reference to record to structs section

[btihen]

Purpose: Better documet Records. It was mentioned on gitter that there is a simplified way to create data structures (structs) in crystal using Records -- which isn't documented in the Crystal git book.

So I was hoping to document the usage and how they can provide flexible immutable data types.

[straight-shoota]

Thanks for helping to improve the documentation!

The reason why record is not documented here is because it's not part of the language. It's a macro provided by the standard library and acts as syntactic sugar for declaring a struct type.

This book is intended to be a reference of the language, while the standard library is documented at https://crystal-lang.org/api. And that's where you can find the documentation for record: https://crystal-lang.org/api/0.32.1/toplevel.html#record(name,*properties)-macro

If you have suggestions to improve the documentation, please add it to the stdlib API docs in src/macros.cr.

Maybe we could add a hint about record to the structs page, which should only act as a reference to the API docs and help readers find the documentation they're looking for.

[btihen]

Ok -sounds good - feel free to close this. Best wishes, Bill

…

On 2 Jan 2020, at 21:57, Johannes Müller ***@***.***> wrote:  Thanks for helping to improve the documentation! The reason why record is not documented here is because it's not part of the language. It's a macro provided by the standard library and acts as syntactic sugar for declaring a struct type. This book is intended to be a reference of the language, while the standard library is documented at https://crystal-lang.org/api. And that's where you can find the documentation for record: https://crystal-lang.org/api/0.32.1/toplevel.html#record(name,*properties)-macro If you have suggestions to improve the documentation, please add it to the stdlib API docs in src/macros.cr. Maybe we could add a hint about record to the structs page, which should only act as a reference to the API docs and help readers find the documentation they're looking for. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[RX14]

I don't think taking the purely technical view of "this is a macro so it cannot be in the language guide" is helpful to new users. Why not mention records at the bottom of the structs page, that it's a macro, and link to the stdlib documentation?

Discoverability of top-level macros like property, getter, record etc. are low, since people don't think to check the API docs.

If this is where people are looking, why not help them out and forward them on to the right place, with an explanation?

[asterite]

I agree with @RX14

I'd like the docs to explain the language, but saying "By the way, there's this very convenient macro in the standard library which you'll most probably stumble upon or find useful" is helpful for everyone.

[bcardiff]

I agree that mentioning record and other common constructs have a place in the book.

I find it hard to say where records should be mentioned. syntax_and_semantics is the section I see more like a pure definition of the language (and is currently the biggest part of the book) but is not the only part.

I would add records here, though reframing them as an expansion that leads to a struct. And not making it sound like a new concept. To be specific, I would avoid "Like structs, records ... "

[RX14]

I wouldn't document records here. I'd document them in the API docs. There's no need for duplication. But there needs to be a short section which forwards you to the right place with 1 sentence about what they are.

[HertzDevil]

We should do it like Getters and setters: one section at the bottom of the page, one introductory sentence, one snippet, then a link to the API docs entry. The current wording implies records are a first-class concept that is distinct from structs.

[netlify]

✅ Deploy Preview for crystal-book ready!

Name	Link
🔨 Latest commit	f1a4ea7
🔍 Latest deploy log	https://app.netlify.com/sites/crystal-book/deploys/62e3b06a67ca2900096b590f
😎 Deploy Preview	https://deploy-preview-379--crystal-book.netlify.app/syntax_and_semantics/structs
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[straight-shoota]

I have reduced the Records section to a simple example and reference to stdlib docs. I'm also posting a PR to improve the stdlib docs at crystal-lang/crystal#12334