Somes examples could be made clearer

[florian-s-code]

I found that some examples were confusing. I'll explain why it's not clear and I'll suggest a solution at the end.

Error handling

https://github.com/ziglang/www.ziglang.org/blob/master/www/index.html#L725

This example is supposed to show that 'The switch keyword used on an error ensures that all possible errors are handled'. Yet the output is an error: ... not handled. For someone not familiar with Zig, this is only marginally different from error discarded that is shown above. And the errors are literally not handled in this example which contradicts the sentence above. It is also surprising to see an example on the official website that is not compiling.

Compile-time code execution

https://github.com/ziglang/www.ziglang.org/blob/master/www/index.html#L975

Because the example use zig test that compiles and executes the program immediately, the fact that the assert is executed at compile time is not made clear enough. The reader is supposed to either :

• make the difference between a compiler error and a stack trace (They look very similar.)
• or notice that the usual text displayed by the test harness is not present.

Suggestion

In these 2 examples, a sentence explaining why these errors were expected and what it is showing could be added. As I said a compiler error is not what is expected when running official examples. Maybe these are obvious for programmers used to low-level, compiled languages (which I am not) but I think the introduction to a language should aim to be as easily understandable as possible.

[kristoff-it]

Thank you for the report, I think you raise good points. I'm working on a website redesign and I'll do a content pass once I have figured out what the new structure should be.

I do think that some of these points shouldn't be solved in the website but rather in the messages that the compiler produces (e.g. making it clear that you got a compile error when calling zig run, rather than a runtime error, should be made clearer by the compiler itself)