6 ms·

I see what went wrong here. You tried to lean on documentation and Google, you should have just go for the source code. It's quite readable, and it's the recomm

I see what went wrong here. You tried to lean on documentation and Google, you should have just go for the source code. It's quite readable, and it's the recommended way to learn for now. Zig has a few peculiarities, it's not stable yet, you kind of have to follow it's development. https://github.com/ziglang/zig/tree/master/lib/std https://github.com/ziglang/zig/tree/master/lib/std

meheleventyone 5y ago
Yeah I did AoC a few years ago in Zig and found sticking the std path in my project so I could quickly search it was the best tool to figuring out how to do various bits and pieces.
- rhodysurf 5y ago
  I did the same! Cuz at the time there was no language server available beyond syntax highlighting and linting. But now there is a pretty good language server package available which is really helpful giving autocompleting
coldtea 5y ago
>I see what went wrong here. You tried to lean on documentation and Google, you should have just go for the source code. That sounds rather like a different thing was wrong - not where the author tried to lean: Zig has crap documentation.
- bollu 5y ago
  Zig documentation isn't crap; the documentation *does not exist* yet. There's an important difference between the two which seems to be ignored. Zig is young. They're spending their time maturing the core ecosystem --- the compiler, the standard library, and so forth. It's perfectly reasonable to expect early adopters to "RTFS/read the fucking source". *When* they start writing documentation, I'd be perfectly happy to hear comments like "The zig documentation is crap". At this stage of the project, I'll be honest, I find it upsetting to read comments like this.
  - rootlocus 5y ago
    Zig absolutely has documentation: https://ziglang.org/documentation/master/ https://ziglang.org/documentation/master/
    - delphLonepaw 5y ago
      That's the language reference, that also links the experimental autogenerated std documentation Right now, Zig is young and the documentation is kinda ok (Language reference is clear enough, outside a few things that need better visibility, for example, explaining concepts that are only on the examples can be lost easy), the autogenerated std on the other hand used to work meh, until a commit broke it afaik, so rn is in a pityfull state, but there is no use in reworking it until stage 2, so that's that
      - rootlocus 5y ago
        Well, the STD documentation page has a red banner saying it's experimental and you should consider reading the code (which worked great for me) so at least you have a warning.
  - coldtea 5y ago
    >Zig documentation isn't crap; the documentation does not exist* yet. There's an important difference between the two which seems to be ignored.* Well, crap as an offering (what you get atm), not necessarily as in the quality of what little it is. It does though have a reference and documentation page: https://ziglang.org/learn/ https://ziglang.org/learn/
    - kristoff_it 5y ago
      The autogenerated docs immediately greet you with a red banner that states These docs are experimental. Progress depends on the self-hosted compiler, consider reading the stdlib source in the meantime. It also links to a page that explains how the standard library is structured: https://github.com/ziglang/zig/wiki/How-to-read-the-standard-library-source-code https://github.com/ziglang/zig/wiki/How-to-read-the-standard...
andi999 5y ago
Recommended way to learn for now? Any sources for that?
- delphLonepaw 5y ago
  Read the language reference, use ziglings, use ziglearn.org, use zls (don't trust it too much tho, but it will help a bit) and vscode or any text editor that supports jumping to the source, and of course, RTFS
  - rootlocus 5y ago
    Read The Fabulous Sources?
    - delphLonepaw 5y ago
      That's a way of reading it
      - mst 5y ago
        When saying it positively I often say UTSL instead (Use The Source, Luke).
        andi999 5y ago
        Isnt the problem with that approach you have a model of the implementation (and not of the 'interface')? I mean you dont know if you are useing the function as intended and if not used as intended it might (actually will) break in the future. For auditing you are right, of course.
        mst 5y ago
        Not exactly. I mean, as a first note one of the ideas here is reading code already written in zig to understand how to write code in zig - so in that case you're effectively inferring the interface from what the authors of the code itself are treating said interface to be. But also, interface documentation is pretty much never truly complete because there are almost always some implicit assumptions involved (and if you try and make all of those explicit you rapidly end up with documentation that's so verbose people's eyes glaze over when they try to read it so their model often ends up incomplete anyway so how explicit to be is itself a trade-off). Then zig embeds its test cases in the source file, so you can look at what the authors have explicitly declared -must- work to help you know what the interface is intended to be. Plus when I'm source diving, I've done enough of it over the years to be able to at least attempt to build up a model of not just the implementation, but of the author's mental model as they were implementing it, and if you can figure out their intent, it's much easier to guess what their code is -meant- to do and thereby what it will hopefully continue to do into the future. If in doubt, though, leaving a comment in your own code as to what assumption you're making -and- writing a unit test in your own code that verifies the assumption continues to hold will mean that at least if it doesn't you'll see a test failure in your own suite that tells you it changed. (or: "code to the interface, not the implementation" is absolutely the right thing to aim for, but in practice the line between the two is fuzzy and cases where you have to make a judgement call will always show up eventually)

meheleventyone 5y ago

Yeah I did AoC a few years ago in Zig and found sticking the std path in my project so I could quickly search it was the best tool to figuring out how to do various bits and pieces.

rhodysurf 5y ago
I did the same! Cuz at the time there was no language server available beyond syntax highlighting and linting. But now there is a pretty good language server package available which is really helpful giving autocompleting

coldtea 5y ago

>I see what went wrong here. You tried to lean on documentation and Google, you should have just go for the source code. That sounds rather like a different thing was wrong - not where the author tried to lean: Zig has crap documentation.

bollu 5y ago
Zig documentation isn't crap; the documentation *does not exist* yet. There's an important difference between the two which seems to be ignored. Zig is young. They're spending their time maturing the core ecosystem --- the compiler, the standard library, and so forth. It's perfectly reasonable to expect early adopters to "RTFS/read the fucking source". *When* they start writing documentation, I'd be perfectly happy to hear comments like "The zig documentation is crap". At this stage of the project, I'll be honest, I find it upsetting to read comments like this.
- rootlocus 5y ago
  Zig absolutely has documentation: https://ziglang.org/documentation/master/ https://ziglang.org/documentation/master/
  - delphLonepaw 5y ago
    That's the language reference, that also links the experimental autogenerated std documentation Right now, Zig is young and the documentation is kinda ok (Language reference is clear enough, outside a few things that need better visibility, for example, explaining concepts that are only on the examples can be lost easy), the autogenerated std on the other hand used to work meh, until a commit broke it afaik, so rn is in a pityfull state, but there is no use in reworking it until stage 2, so that's that
    - rootlocus 5y ago
      Well, the STD documentation page has a red banner saying it's experimental and you should consider reading the code (which worked great for me) so at least you have a warning.
- coldtea 5y ago
  >Zig documentation isn't crap; the documentation does not exist* yet. There's an important difference between the two which seems to be ignored.* Well, crap as an offering (what you get atm), not necessarily as in the quality of what little it is. It does though have a reference and documentation page: https://ziglang.org/learn/ https://ziglang.org/learn/
  - kristoff_it 5y ago
    The autogenerated docs immediately greet you with a red banner that states These docs are experimental. Progress depends on the self-hosted compiler, consider reading the stdlib source in the meantime. It also links to a page that explains how the standard library is structured: https://github.com/ziglang/zig/wiki/How-to-read-the-standard-library-source-code https://github.com/ziglang/zig/wiki/How-to-read-the-standard...

andi999 5y ago

Recommended way to learn for now? Any sources for that?

delphLonepaw 5y ago
Read the language reference, use ziglings, use ziglearn.org, use zls (don't trust it too much tho, but it will help a bit) and vscode or any text editor that supports jumping to the source, and of course, RTFS
- rootlocus 5y ago
  Read The Fabulous Sources?
  - delphLonepaw 5y ago
    That's a way of reading it
    - mst 5y ago
      When saying it positively I often say UTSL instead (Use The Source, Luke).
      - andi999 5y ago
        Isnt the problem with that approach you have a model of the implementation (and not of the 'interface')? I mean you dont know if you are useing the function as intended and if not used as intended it might (actually will) break in the future. For auditing you are right, of course.
        mst 5y ago
        Not exactly. I mean, as a first note one of the ideas here is reading code already written in zig to understand how to write code in zig - so in that case you're effectively inferring the interface from what the authors of the code itself are treating said interface to be. But also, interface documentation is pretty much never truly complete because there are almost always some implicit assumptions involved (and if you try and make all of those explicit you rapidly end up with documentation that's so verbose people's eyes glaze over when they try to read it so their model often ends up incomplete anyway so how explicit to be is itself a trade-off). Then zig embeds its test cases in the source file, so you can look at what the authors have explicitly declared -must- work to help you know what the interface is intended to be. Plus when I'm source diving, I've done enough of it over the years to be able to at least attempt to build up a model of not just the implementation, but of the author's mental model as they were implementing it, and if you can figure out their intent, it's much easier to guess what their code is -meant- to do and thereby what it will hopefully continue to do into the future. If in doubt, though, leaving a comment in your own code as to what assumption you're making -and- writing a unit test in your own code that verifies the assumption continues to hold will mean that at least if it doesn't you'll see a test failure in your own suite that tells you it changed. (or: "code to the interface, not the implementation" is absolutely the right thing to aim for, but in practice the line between the two is fuzzy and cases where you have to make a judgement call will always show up eventually)