langref: Explain Zig Test #9858
Conversation
paulespinosa
force-pushed
the
langref-explain-zig-test
branch
2 times, most recently
from
e9ec474 to
eeea9a6
Compare
|
This is great and indeed a very useful thing to document! |
There was a problem hiding this comment.
A thorough explanation that does not leave open many questions. Its a good read, but not dense yet.
Necessary changes
dont breakchanging code to be untested in the langref is not good- properly document the plan for containers
- make the list of notable/most frequent functions for tests dense, ideally a table
- once review is finished a rebase to change commit message
|
|
||
| test "comments" { |
There was a problem hiding this comment.
Please dont change test code to normal functions, because the respective code in the langref then becomes untested.
There was a problem hiding this comment.
What should we do to address the concerns raised in #8221 and #5837 while working towards the goals of #1524? The comment #8221 (comment) points out "The first Hello World example is explained beautifully. The second example uses the syntax test string { block }, but does not explain what the semantics of this is."
We have several options to make this work well. Which option do you suggest?
There was a problem hiding this comment.
I do see 2 solutions: 1. move tests right after hello world, but this feels weird cause we want to test against certain expected values. 2. Make a short sentence that the semantics is explained later and that regular zig code can be used within tests, but test code is only excecuted for testing.
Do you see another solution?
There was a problem hiding this comment.
Can you elaborate on 1, please? I think we've come up with the same two ideas (#5837) if I'm understanding 1.
Another option: take a look at the Values example, it uses main and assert. If we must test something, we could use the same technique until the Zig Test section.
If we decide to leave the Zig Test section further down, I urge you to consider what's being changed here. Generally, we wouldn't want to change tests, but the context should be part of the decision.
There was a problem hiding this comment.
Can you elaborate on 1, please?
My reason to explain 1 was to elaborate why it is a bad idea: Describing tests does not make sense to me, if the reader does not know against what the reader can test (Values). How these values manifest (Variables) is not of utter importance to understand the concept.
I urge you to consider what's being changed here
test blocks were changed to main functions.
| @@ -896,24 +820,25 @@ pub fn main() void { | |||
| in recent versions of the Unicode specification (as of Unicode 13.0). | |||
| In Zig, a Unicode code point literal corresponds to the Unicode definition of a code point. | |||
| </p> | |||
| {#code_begin|test|string_literals_test#} | |||
There was a problem hiding this comment.
same argument: dont make code untested.
|
Thanks @matu3ba. By the way, are you on the core team? |
paulespinosa
force-pushed
the
langref-explain-zig-test
branch
from
71d59fd to
04a72a4
Compare
Updates the Language Reference sections: Comments, Values, and Zig Test. Zig Test section moved down with the goal "make sure it can be read top to bottom sensibly" in mind (issue ziglang#1524). Comments and Values section examples changed test declarations to a main function and expect statement to print statements. A print statement was added to the "String Literals and Unicode Code Point" section's example to demonstrate the "u" format specifier. Zig Test Section: * Addresses the question: "How does the syntax work?". * Partially answers the question: "What can I do with the zig test tool?" but should be sufficient to understand the examples in all of this document. * Addresses the question: "How does a top-level test block differ from a function definition?" * Provides a example to run multiple test. Lacks clear definitions of containers, top-level, order independence, lazy analysis, resolve, reference. GitHub Issues: ziglang#8221, ziglang#8234
paulespinosa
force-pushed
the
langref-explain-zig-test
branch
from
04a72a4 to
ee04b58
Compare
No. My compiler_rt contributions are not merged (yet) and would not be sufficient for that. As I understand it they are also not necessary for selfhosting, but for zig without LLVM. |
|
Nice improvement, thank you! |
Updates the Language Reference sections: Comments, Values, and Zig Test.
An example of the changes can be found at:
https://paulespinosa.github.io/zig-langref/explain-zig-test-01.html#Zig-Test
Zig Test section moved down with the goal "make sure it can be read top to
bottom sensibly" in mind (issue #1524).
Comments and Values section examples changed test declarations to a main
function and expect statement to print statments.
A print statement was added to the "String Literals and Unicode Code Point"
section's example to demonstrate the "u" format specifier.
Zig Test Section:
should be sufficient to understand the examples in all of this document.
assert isn't recommended to be used in tests and the information exists under
unreachablesection.
Lacks clear definitions of containers, top-level, order independence, lazy
analysis, resolve, and reference. The issue #9857 has been created to add this
information to the document.
GitHub Issues: #8221, #8234
This pull request is produced from feedback given by @matu3ba in a previous pull request #9737.