Docs logical operators typo (and other suggestions)

[Kiyoshi364]

https://odin-lang.org/docs/overview/#logical-operators

Third column, second line: There is:

||     conditional or      a && b    is  "true if a else b"

(the amount of spaces is arbitrary) Should it be, that?

||     conditional or      a || b    is  "true if a else b"

Note that, I'm not sure if it is known. I quickly searched in open issues, and didn't find something similar. I just dropped from docs website.

[mtarik34b]

While at it "conditional or" could be capitalized to "conditional OR" just like with "AND" and "NOT".

[mtarik34b]

While at it "conditional or" could be capitalized to "conditional OR" just like with "AND" and "NOT".

[Kiyoshi364]

I have other suggestions, I'll append " (and other suggestions)" at the end of the title, I think that one issue with all my suggestions is better. I'm slowly reading it, so there may be more in the future.

More suggestions (assume that the first is indexed by 0):

(1) https://odin-lang.org/docs/overview/#swizzle-operations

Second code block: It was not immediate to me that c == Vector3{ 3.5, 7, 11.5 } Could there be an assert just after the declaration?

(2) https://odin-lang.org/docs/overview/#slices

At the end, is written:

The built-in len proc returns the array’s length.

The section is about slices and the following example is abou slices. Should it be "slice's length"?

[Kiyoshi364]

(3) https://odin-lang.org/docs/overview/#bit-sets

When listing the bit sets supported operations, I spent a lot of time analyzing &~ (bitwise and-not). From my understanding:

#assert( 0b1100 &~ 0b1010 == 0b0111 )
#assert( 0b1100 & (~0b1010) == 0b0100 )

Assuming that my asserts are ok, it doesn't make that much sense to say that &~ represents "difference of two sets".

After a while I realized that there is no need for the setwise operations to be implemented using the corresponding bitwise operations.

Something similar happened with ~ ("symmetric difference" and "bitwise xor").

If I got every thing right, my suggestion is to add a note, n.b. ou equivalent before or after the list of bit set operations.

Note that this confusion may be caused/related by/with the previous paragraph, which talked about the underlying bits implementation. Some reordering may relieve the problem.

(4) https://odin-lang.org/docs/overview/#swizzle-operations

In the second code block the .x notation without any explanation. I find it intuitive enough, but I asked myself: can I do something similar with length 4? Length 10? ... Can I do that with other names (ex: .r or .arbitrary)?

I kinda got answered latter in: https://odin-lang.org/docs/overview/#soa-struct-arrays

Works with arrays of length <= 4 which have the implicit fields xyzw/rgba

My suggestion is add a small section or paragraph in https://odin-lang.org/docs/overview/#array-programming before "Swizzle Operations".

(5) Nitpick: https://odin-lang.org/docs/overview/#soa_zip-and-soa_unzip

In the first code block, in for loop

fmt.println(v, i) // exactly the same as s[i]

Can it be said more explicitly that v === s[i]? Something like

fmt.println(v, i) // v is exactly the same as s[i]

Also, === is not explicitly defined. I assumed "is exactly the same as" (basing on the previous comment). But this is a nitpick inside a nitpick (maybe it is safe to ignore :P).

[Kiyoshi364]

(6) https://odin-lang.org/docs/overview/#foreign-system

In the last code block, maybe missing // on lines 2 and 4 (starting from 1). Those lines look like comments:

default_calling_convention=<string>
    default calling convention for procedures declared within this foreign block
link_prefix=<string>
    prefix that needs to be appended to the linkage names of the entities except where

Should it be, something like

default_calling_convention=<string>
    // default calling convention for procedures declared within this foreign block
link_prefix=<string>
    // prefix that needs to be appended to the linkage names of the entities except where

[Kiyoshi364]

(7) https://odin-lang.org/docs/overview/#what-to-do-if-you-get-stuck

A typo at the end of the 2nd item of the list:

Tests are also guaranteed to be up-to-date (if regularly run), unlike more informal documenation.

Should it be "documentation" instead of "documenation"?

I have reached the end of the docs/overview. I'd like to remark that I'm not even sure if I'm doing this in the right place.

For some context, I'm really interested in programming languages, but there are so many, that I can't try them all. So instead of grabbing a compiler and making a small project, I grab the docs, read it and put in some kind of priority queue to try latter. This has been a nice compromise between looking at many languages and actually trying them.

I'm saying that, because in some examples there were prints without comments telling what they print. So here goes one more:

(8) General suggestion for future docs

Prefer asserts to prints. This allows readers to verify what the code does by "believing that the assertion is true", instead of actually running the code. Also, makes it easier to turn those code snippets into tests. Here is a quote from the docs itself:

Tests are essentially automatically verified documentation. Tests often cover details that normal documentation doesn’t even mention. Tests are also guaranteed to be up-to-date (if regularly run), unlike more informal documenation.

(I'm leaving the typo there)

A non exhaustive list of places where I think it would be helpful:

• https://odin-lang.org/docs/overview/#procedures
• https://odin-lang.org/docs/overview/#parameters (in first 2 and last blocks)
• https://odin-lang.org/docs/overview/#multiple-results
• https://odin-lang.org/docs/overview/#swizzle-operations
• https://odin-lang.org/docs/overview/#structs
• https://odin-lang.org/docs/overview/#maps
• (I'm stopping here)

[jon-lipstate]

#assert( 0b1100 &~ 0b1010 == 0b0111 )
#assert( 0b1100 & (~0b1010) == 0b0100 )

Your paren in the second assert evaluates out, the language in the docs, while maybe a bit opaque, it is correct. The bits in a that are not in b. in this case 0b0100 fits the bill.

package scratch
import fmt "core:fmt"
main :: proc() {
    a: u8 = 0b1100
    b: u8 = 0b1010
    //~b=1111_0101
    fmt.printf("0b%b\n", a &~ b)   // 0b100
    fmt.printf("0b%b\n", a & (~b)) // 0b100
}

[Kiyoshi364]

(I lost the original comment for some reason, so I'm rewriting from memory, I may have forgotten some details) I'll list what I understood from the commit.

Suggestions covered by the commit:

• (0)
• (2)
• (4)
• (6)
• (7)
• (8) Awesome, using prints but having an "output block" solves it.

Suggestions that were ambiguous or unclear:

• (1) I'd like something like:

  Vector3 :: distinct [3]f32
  a := Vector3{1, 2, 3}
  b := Vector3{5, 6, 7}
  c := (a * b)/2 + 1
  fmt.printf("%.1f %.1f %.1f\n", c.x, c.y, c.z) // 3.5 7.0 11.5
  d := c.x + c.y + c.z
  fmt.printf("%.1f\n", d) // 22.0

  To show the values of c. Array programming may not be immediate to newcomers.

• (3) I misunderstood what a &~ b meant. I read like NOT(AND(a, b)) but it actually is AND(a, NOT(b)).

I don't see &~ as a common operator in programming languages. So, my suggestion changes to: add a note that states something like: "a &~ b is equivalent to a & (~b)".

About ~ (symmetry difference), I just missed what it meant. I think that saying "a ~ b is equivalent to (a | b) - (a & b)" helps those who are not used to the name symmetric difference.

• (5) From reading the comment I understood that "*something in the statement fmt.println(v, i) is equivalent to s[i]. From context and general programming knowledge, I guessed that the *something is the expression v. Prepending "v is " to the comment solves it:

  fmt.println(v, i) // v is exactly the same as s[i]

About ===, it only appears once in the entire web page, and I don't like it being there. I don't know how to solve it. Maybe it should be there until a next rewrite (?)