What are the best param documentation patterns for Zig?

We all should know top-level doc comments (//!) and doc comments (///).
Now, in many programming languages, there is some kind of standard pattern for documenting what the parameters mean and what the meaning of the returned value (if the function has one) is.

In Python, we have :param something:, in JavaScript we have @param something, what are standard patterns you use in your Zig code?


I don’t think one has solidified. The standard library just speaks to the parameters as needed. (See openFileAbsolute as an example in std.fs).

In languages like Python and JS, where typing is optional or non-existent, I find those conventions very helpful for describing the type of data expected. Less necessary in statically typed declarations.


The ones that need the most explanation are anytype parameters. I’ve run into that problem on something I’m working on right now actually.

@Calder-Ty is right that the type system documents a lot on its own.

I tend to find that libraries and projects are what need the most clarification and individual functions are then easier to understand in context. Maybe that’s just me.


Not an answer, but tacking onto the question, I think a useful case for this style of doc would be resolving ambiguity over whether a struct is meant to be initialized directly, or through a new()/init() function namespaced to the struct. Also resolving ambiguity over which fields of a struct are intended to be accessed directly or not. Private fields aren’t getting added to the language per Andrew:

And I think some sort of doc string might be a nice alternative approach to his method of indicating intent via struct field names.


Note that you can add doc comments to parameters directly.

Example from the standard library:

How it looks in autodoc:



That looks great on auto-doc, actually. Very nice.

1 Like

I thought this was broken for a while. Glad to see I was either wrong or it’s fixed!

I believe it got fixed in the autodoc redesign: