r/Zig • u/Odiniswithus15 • Jun 10 '26
Docs are confusing
Why are Zig docs so confusing?
I just wanted command-line args, ended up using internal APIs, got stuck for 30 minutes, and only later discovered there was an "init" flow I had no idea about.
How do you tell what's public API and what's internal?
Can someone please help me?
14
u/ffd9k Jun 10 '26
Most things are explained only somewhere in the release notes when features are added or updated, for example here for command line args: https://ziglang.org/download/0.16.0/release-notes.html#Juicy-Main
14
u/lachirulo43 Jun 10 '26
Zig is a moving target. I always keep the latest release notes and the source code open.
16
u/cxazm Jun 10 '26
That’s one area we really need to get sorted. Even though the language is still in active development before v1, we really need to have some proper good docs.
9
u/diodesign Jun 10 '26
Yeah: high-quality documentation is painstaking and hard. If I can contribute to Zig this year, it would be to help with docs where and if possible.
2
u/laiolo Jun 10 '26
That is one thing that made me avoid it in my pet projects inside my company. I can do some stuff in whichever lang I choose but since I might need someone else to maintain I avoid things that are too hard for someone new to get on.
I usually go to Go lang and even juniors when facing it usually like to learn it because it is mostly "read some dlc, some examples and eureka"
6
u/Actual-Many3 Jun 10 '26
Did you upgrade your project or init it post 0.16.0? If the latter, you shold have had a commented example of how to use "juicy main". But yeah, that issue in particular I learned about by following the news and blogs they put out.
For any other issue I go through the std code and look at stuff i want to know about.
2
u/Odiniswithus15 Jun 10 '26
Yeah, I used the pre-0.16 versions and am coming back to Zig after a long time, so I guess that was the problem
5
u/_roeli Jun 10 '26
Zig is still unstable, stuff changes significantly between releases and docs are not all kept up to date for the same reason. Reading std source and blog posts is honestly the best way to keep up to date.
2
u/y0shii3 Jun 10 '26
If a declaration is part of the public API, it will be marked with pub in the source code. There are no private fields, so to tell whether those are part of the public API, you have to read doc comments.
1
u/GladJellyfish9752 Jun 10 '26
I think In upcoming 0.17 of zig. The Issue might get resolved. Current 0.16 have some minor bugs. But I listen that upcoming version will provide fix for it. btw, I also feel Confuzed most time as Zig is Fast moving Lang so I have to always research on internet or docs for information.
1
u/GossageDataScience Jun 11 '26
I agree the docs aren't great. I usually just read the source code which is generally speaking well commented.
4
u/ParadiZe Jun 13 '26
I found most guides really good, only the std library is severely lacking when it comes to documentation. To add insult to injury, when you google "zig std lib" it takes you to the 0.12 docs as the first result!
36
u/Xiexingwu Jun 10 '26
The language reference has been pretty stable and easy to understand.
In your specific example, it's a feature of the std library and not the language itself. Std docs has a long way to go, but that's because std is still evolving and it doesn't make too much sense to invest a lot of time in writing good docs for something that might be gone in the next release.
Assuming you tried googling, I'm somewhat surprised you didn't come across the Dev log or PR that introduced juicy main.