crystal-lang / crystal-book Goto Github PK

Just a heads up that the "Documenting Code" page still uses doc instead of docs. I was wondering why crystal doc wasn't working! Also note that the default directory doc/ has been changed to docs/ as well.

I used ag to search for other occurrences of doc and plan to submit a pull request that fixes this.

I'd like to see the link of the readable book here somewhere:

ensure must come after else, but this is not specified on the exception handling page. In fact, that page actually defines ensure before else.

See original request: crystal-lang/crystal#4365

The fresh_vars_sample(*names) on https://crystal-lang.org/docs/syntax_and_semantics/macros/fresh_variables.html does not output

# Declaring: __temp_255
# Declaring: __temp_256
# Declaring: __temp_257
# __temp_255: 0
# __temp_256: 1
# __temp_257: 2

as the example claims, but instead output

Declaring: %name{index}
Declaring: %name{index}
Declaring: %name{index}
%name{index}: 0
%name{index}: 1
%name{index}: 2

(crystal 23)

The command literals `whoami` and %x(whoami) need to be documented.

Continuing discussion from: crystal-lang/crystal#5002

Search usually works fine but for some search terms it fails and there are no results nor error messages on the page. For example, search for char
The JavaScript console shows this error:

lunr.min.js:7 Uncaught TypeError: Cannot read property 'tf' of undefined
    at t.Index.documentVector (lunr.min.js:7)
    at t.Index.<anonymous> (lunr.min.js:7)
    at Array.map (<anonymous>)
    at t.SortedSet.map (lunr.min.js:7)
    at t.Index.search (lunr.min.js:7)
    at LunrSearchEngine.search (search-lunr.js:34)
    at Object.query (search-engine.js:31)
    at launchSearch (search.js:79)
    at handleUpdate (search.js:121)
    at HTMLInputElement.<anonymous> (search.js:142)

According to olivernn/lunr.js#243 this might be caused by lunr.js having issues with unicode codepoints like emojis. There is an emoji (🔮) in the book on both pages about char and string literals and it fails to search for any terms that appear on one of these pages. I am not 100% sure about it, but this looks like strong evidence.

This failure should be fixed in lunar.js but until then, we should try to find a workaround for Crystal Book.
I think we could just remove the emojis from the pages. It's nice to have them there but they're not essential. Perhaps we could also manually remove them from the search index.

While working with the amber framework, specifically reading the granite orm code I ran across the property keyword.

Searching the language docs I came up empty with much of an explanation as to what is going on. The search results point to two articles which use the keyword (Attributes and Structs) and three articles matched on stemming ("properties") but still did not give a concrete definition of the keyword and its purpose.

Crystal for Rubyists does clarify the meaning with it's table comparing it to Ruby's #attr_accessor, but I don't see this mirrored in the official documentation anywhere.

This seems like a hole in the documentation but I'd like to get a sign off from someone marked as a contributor about where and what the documentation should say about the keyword before submitting a doc pull request.

When crystal-lang/crystal@e872c71 is released, the section should be removed.

(Moved here from crystal-lang/crystal#3135)

I just noticed the documentation seems to be missing the description of the getter/setter macros. The property macro is used in the Structs page though.

Also, I saw in source code that obj.@var is valid, and I guess it's field access without "method call" (even if there was a getter method that might do something else in addition)? This syntax isn't explained either in the documentation.

Of course one can learn these things through other ways too. Just putting it out there so it won't get forgotten in case the documentation is supposed to be comprehensive. If wanted, and if my assumptions are correct, I could describe it somewhere. But I doubt my writing style is as beautiful as the one in Crystal's documentation. :)

See: https://crystal-lang.org/docs/syntax_and_semantics/literals.html

The regex section is causing the third column to be added. A quick workaround is to change the example to one that doesn't use |.

Review the whole book and change any mention to itself to "Language Reference"

Error: ENOENT: no such file or directory, lstat '/home/chun/.cache/mozilla/firefox/mwad0hks.default/cache2/entries/E4499943457122601C382ABE781A0BE6FE3585DF'

The current file does not explain what the difference is between blocks and procs.

I get the impression that a Block is a more primitive thing than a Proc. If that's true, at what point does a block become a proc?

How are these two things related?

It would be helpful to have all the keywords of crystal language in a page.

Examples:

• https://docs.oracle.com/javase/tutorial/java/nutsandbolts/_keywords.html
• https://golang.org/ref/spec#Keywords

It would be helpful for people coming from other ecosystems to get the idea of available keywords.

There is this example in the book:

if a.is_a?(String) && b.is_a?(Number)
  # here a is a String and b is a Number
end

But what about using || in this scenario with the same variable?

if a.is_a?(String) || a.is_a?(Number)
  # There is no guarantee that a is bound to anything?
end

I need a better explanation of

local ||= 1 # same as: local || (local = 1)
local &&= 1 # same as: local && (local = 1)

Wouldn't this example code make more sense as

local ||= 1 # same as: local = local || 1
local &&= 1 # same as: local = local && 1

I'm still not sure of the use case for &&=, but I'm pretty sure my comments make more sense than the original.

Am I way off here?

Related discussion with @RX14 on gitter

Andy Fleming @andyfleming 16:14

I say we break "Methods and instance variables” into “Instance Variables” and “Instance Methods”. Then we start with manual getters and setters, then introduce the shorthand and the property concept. It would be nice and clean. Then in the “Instance Methods” page, we can use the shorthand.

@RX14 16:14

hmm

i think "new, initialize and annlocate" should be merged into "methods and instance variables" somewhat too

that area of docs keeps coming up as a pain point

Andy Fleming @andyfleming 16:16

Yeah

allocate seems like an advanced topic that shouldn’t be mixed in with creation of class instances

(though a mention/link might be appropriate)

Firstly thank you for the wonderfully thought out and designed resource.

I noticed that in methods_and_instance_variables.md there's a code snippet:

class Person
  def initialize(@name : String)
    @age = 0
  end
end

Followed by:

Right now, we can't do much with a person: create it with a name, ask for its name and for its age, which will always be zero. So lets add a method that makes a person become older:

But - really - we can't query the state of @age or @name without using getter :age, :name.

If you feel like this is big enough to address I can send a PR...perhaps...

Right now, we can't do much with a person aside from create it with a name. Its age will always be zero. So lets add a method that makes a person become older.

The current section Types and Methods - Classes and Methods is muddy.

Since methods can exist on their own, outside of classes, methods should be their own chapter. Classes as a following chapter can expand on methods.

Hi, I found it spend lots of time on page changing (because they are different html page), can you provide one page version? Thanks.

At the end of this page it says:

When a method specifies a splat (explained in the next section), named arguments can't be used. The reason is that understanding how arguments are matched becomes very difficult; positional arguments are easier to reason about in this case.

but then in the next section it says:

Arguments past the splat argument can only be passed as named arguments.

Since it seems that named arguments can be used with a splat, I think the last paragraph of the first page I linked should either be removed, or changed to say that positional named arguments cannot be used with a splat but non-positional named arguments still can.

Right now it says "There are four signed integer types: Int8, Int16, Int32 and Int64, being able to represent numbers of 8, 16, 32 and 64 bits respectively."

I think it would be much better to show the range of values that can be represented with those classes. It makes for a far better explanation. I'm happy to write the revision myself, I just want to run it by the core team first.

this page doesn't seem to document then.

In the book it says that the following code does not work:

class Parent
  @@counter = 0
end

class Child < Parent
  def self.counter
    # Error, can't infer the type of class variable
    # '@@counter' of Child
    @@counter
  end
end

However, since v18 this is not the case anymore.

For a new user of crystal, if they goto the website and click "LEARN", they are taken to this page: https://crystal-lang.org/docs/overview/

The flow of pages from there is:

• Overview - basically how to read the code samples, and suggesting jumping through the docs
• Hello World! - A hello world puts statement with some explanation
• HTTP Server - A short walk-through creating a basic HTTP server
• Syntax and Semantics - "The program’s source code must be encoded in UTF-8."
• Comments - Description of how code comments work
• Literals - "Several literals are available for creating many basic types in the language."
• Nil - Short explanation of nil
• Bool - Short explanation of bool
• Integers - Detailed explanation of Integers
• Float, etc. The data types with detailed explanations continue from there

There are a few ways this could be improved. It may be that "LEARN" links somewhere else, instead of changing crystal-book itself or these changes may improve the experience:

• The order could be improved, the user goes from `puts "Hello World!" straight to an HTTP server (a bit "How to draw an Owl"-like).
• Some pages (e.g. "Syntax and Semantics") are one or two sentences and could be combined.
• Summaries of all the listed data types could be provided on one page, then details linked from there.

It may be best to have a different place for "LEARN" that is more tutorial style, similar to https://tour.golang.org

Until that can happen, perhaps improving the flow for this part of the guides is low-hanging fruit.

In crystal-book/syntax_and_semantics/c_bindings/type.md one finds the following note:

Thus, a type declaration is useful for opaque types that are created by the C library you are wrapping. An example of this is the C FILE type, which you can obtain with fopen.

Any chance of some elaboration or clarification on that? I ran against this while (sigh) trying to make use of the OpenLDAP library, which has an opaque LDAP struct, and... I had and have no idea how to deal with that, despite this note. Just me?

Hey all, so far I have seen a vim plugin and a sublime text plugin. I think there should be a section on editor support in the docs. Happy to write it in.

The following command are needed for installing on Debian 9:

sudo apt-get install apt-transport-https dirmngr libssl-dev zlib1g-dev gcc

dirmngr is used by the current setup.sh script but is not default installed. Without this the shell script breaks and you can not even install crystal as a trusted source.

apt-transport-https and libssl-dev are used by the webserver example compilation
gcc is needed for the linker, no gcc = error during compilation
zlib1g-dev ... fixes compile error.

With any of them missing, its impossible to compile crystal on a fresh installed Debian 9 installation.

For WSL on Windows ( This may also apply to the Ubuntu installation seeing as WSL = Ubuntu ):

sudo apt-get install libssl-dev

If they are missing from the setup.sh script, Crystal will fail to install or compile for instance the web example on Debian/WSL/Ubuntu.

See title.

Is there any available alternative to the --with-llvm flag in the Homebrew installation of Crystal?

See: crystal-lang/crystal#3894

I found that there is no content about spec, I have no idea about what spec is, is it like something about test module? Maybe it is better to have something about that. :)

The page Global Variables is obsolete and has been removed from the repository (e8d4843) but is still displayed on the public website.

It seems like the deployment to S3 doesn't take care of removed pages and leaves them accessible forever.

Now that we're referring to this book as "language reference" instead of "documentation" (#78), we could reflect the change in the URI. This will hopefully reduce a frequent source of confusion for newcomers to the community: many expect to find under /docs what we put under /api.

IMO It would be great it at the footer of each page an "edit page" link would link to the .md source.

It will help for this repo discovery and will engage people to contribute.

Installation on Debian unlike on Ubuntu raises a few issues that is unique to only itself. Like the need for apt-transport-https. I personally had to Google a lot to install crystal. Would be great if the documentation be made more elaborate to suit a beginner .

I am willing to work on it. Should I?

The section Passing a closure to a C function contains example code that does not compile.

See crystal-lang/crystal#5528 for initial report.

I believe it would be beneficial if the crystal reference had a section that explains how to use shards in a project. I tried searching shards update, for example, and couldn't find any relevant information.

It may also help to:

1. Add a man page for shards. This makes sense since there's already one for crystal (consistency).
2. Add a brief description about each option to shards --help. This would also make it consistent with crystal --help.

My initial question: What is the difference between shards update and shards install? When I tested them, they both functioned identically to me so I wanted to know what they actually do.

The crystal book chapter on hooks doesn't include finished:

Special macros exist that are invoked in some situations as hooks: inherited, included, extended and method_missing.

Should it?

The documentation on requiring files need to be changed to lib instead of libs.

I have a push request for this in the works that also clarifies how to get require to use the right path since it took me a while to get it right.

For reference, see crystal-lang/crystal#321 and crystal-lang/crystal/pull/2788.

How does immutability work with constants?

Constants can invoke methods / expressions? So they can be assigned something at runtime, but cannot be re-assigned something?

Include more examples for this.

Hi,

I'm willing to contribute helping to translate the Official Docs to Brazilian Portuguese (pt-br). Where can I find the repo for that translation http://br.crystal-lang.org/ ?

I got the following messages when building the documentation.
I run it on ubuntu on windows 10 (WSL).
How to resolve this?

Live reload server started on port: 35729                                                                
Press CTRL+C to quit ...                                                                                 
                                                                                                         
info: 10 plugins are installed                                                                           
info: loading plugin "ga"... OK                                                                          
info: loading plugin "edit-link"... OK                                                                   
info: loading plugin "offline"... OK                                                                     
info: loading plugin "livereload"... OK                                                                  
info: loading plugin "highlight"... OK                                                                   
info: loading plugin "search"... OK                                                                      
info: loading plugin "lunr"... OK                                                                        
info: loading plugin "sharing"... OK                                                                     
info: loading plugin "fontsettings"... OK                                                                
info: loading plugin "theme-default"... OK                                                               
info: found 132 pages                                                                                    
info: found 5 asset files                                                                                
error: error while generating page "syntax_and_semantics/macros.md":                                     
                                                                                                         
Template render error: (/mnt/c/p/crystal-book/syntax_and_semantics/macros.md) [Line 243, Column 9]       
  unknown block tag: end                                                                               

In the Regex page, show an example of a regex literal scanning unicode.

I'm currently working on translation of this repo to Korean. I'll keep working on that even if you won't accept the PR, mainly because I really love this language, but I want to make sure if my translations would be merged to this official repo.

I acknowledge that Crystal lang is still developping and therefore there are many changes to the document. I've updated with 5 commits made to the original repo after I forked it.

My former open source translation contributions include timeago.js, Learn X in Y minutes, Shattered Pixel Dungeon, and Latern. The forked repo is https://github.com/linterpreteur/crystal-book.

Thanks.