Stdlib documentation ideas

A recent article called A “Better C” Benchmark (which I enjoyed quite a bit) brought up the limitations of the current auto-generated stdlib documentation.

It’s widely acknowledged that the stdlib docs leave something to be desired and/or might even be doing more harm than good. Particularity since the stdlib code itself is regarded as very readable and well commented.

On the other hand, handing people a link to ziglang/zig/tree/master/lib/std and saying, “have fun and come home when it gets dark,” isn’t great either.

This got me to thinking about a halfway solution: A human-written “table of contents” of stdlib functionality with a one-sentence descriptions of each type/value/function and a link to the source location for further perusal. Ideally the table of contents would also briefly explain the purpose of each namespace as well as some general tips about which functions to use for which purpose.

The idea would be to give people a starting place for understanding the organization and purpose of the library while still encouraging them to go read the source for more information.

(Note: If this sounds similar to what we currently have with the auto-generated documentation, I didn’t explain it well enough.)

I’m curious what everyone thinks of this idea or if anyone can think of other “light effort” alternatives to “proper” documentation?

2 Likes

I think I lot of the stdlib functions already have docs, I think an in-between for this would be to document as many stdlib functions in the zig source code, but then write a tool that traverses the ast and makes a searchable list of functions - not sema based. This is good because it leaves the doc strings in the zig source for when we have “real” docs. I think this ast docs tool would be fairly easy to write.

1 Like

Sounds neat, but I’m not sure I fully understand it. Extracting information from the AST makes sense, but then where would the related documentation be stored?

I think that the right way to do it should be to explain to people that for now they have to read the stdlib, and that it’s not that hard, once you understand how things are structured. The doc tool will get unblocked not too far from now and, while everyone is obviously free to do whatever they want with their free time, I think the effort to spoonfeed a “stdlib a la carte menu” to people it’s not worth the effort.

I made a video on the subject a while ago:

My personal recommendation is to make a blog post that, somewhat similarly to what the video does, explains how to navigate the stdlib and gives a few examples of use cases that are covered. Ideally a short blog post should cover all the dev personas that don’t like to watch videos and it should be much more valuable as it teaches people to be indepentent.

3 Likes

That makes sense too. Maybe the happy medium is a blog-like informal introduction (your video was already on my to-watch list, but I’ll get to it sooner now!) with some helpful prose and an automated index of the available functions/types.

I do recommend watching the video, the source code is well self documenting and easy to explore. IMO it’s mostly a matter of people wrongly estimating how hard it is to navigate the stblib. That said, you could very well come to a different conclusion after watching it, so let me know!

In a format like json or something. I like your idea, but it seems like a duplication of work since a lot of functions have doc comments already. I am basically saying use the doc comments that are already there.

Ah, yes. I agree about not wanting to duplicate work. Between that and @kristoff 's recommendation about pointing people to the source, I’m thinking trying to describe (even in single sentences) everything by hand isn’t a good “middle ground” after all.

Having perused quite a few relatively “new” programming languages lately, I have seen a tendency towards preparing a really beefed-up single page document that shows you the essentials all in one place. Some call it a “Tour”, others an “Overview” or “Introduction”, but the style is pretty much the same and I find it very effective. In Zig’s case, the Language Reference is what I find fulfilling this purpose and it’s very good, but like @kristoff says in the video, it doesn’t cover the stdlib. Although an auto-generated full blown mega stdlib docs site will be the ultimate reference, I think that an equivalent single page one stop tour for the stdlib like the Language Reference would be excellent. And yes, I also find the Zig source code extremely readable and having good comments and tests, so in the meantime I would go so far as to say that all links to the existing std docs should be replaced with links to the source code. It would be drastic, but less confusing in my opinion.

2 Likes

Many stdlib functions are annotated with a short description of what they do.

Better presentation and searchability are badly needed.

But really, what makes an API documentation great for newcomers is having extensive examples for everything.

This is what makes the Go stdlib pretty nice to work with. It contributed a lot to a good first experience with the language, when we don’t really know what to look for.

Having these examples and “getting started”/“tours” out of the in-code documentation may not be good until the API is stabilized. Guides and tutorials eventually become inconsistent with the versions people have installed, causing confusion.

So, maybe we should spend some time improving the /// comments all across the stdlib (easier to keep consistent with the code) and move to “reference-guide” like documentation later once it is less of a moving target.

3 Likes

Yes, being able to CTRL-F for something in the single-page language reference is awesome. I can’t currently do that for the stdlib. And probably the more compact, the better. I’m starting to imagine a sort of cheat-sheet with tiny bits of explanation thrown around.

1 Like

This is so true! Sometimes a couple short examples demonstrate more than four paragraphs of text could explain.

And not just for newcomers. When I already know/understand what I’m looking for and I want fast answers, all I really want is some examples. :smile:

1 Like

I think a navigation helper to the library would be very useful, although I am not sure what the best way to build this would be.

One idea might be adding some additional meta-data to the /// comments, so that you can not only build reference docs from them, but also build a taxonomy / index. For example, if we were to support adding ///tags: bifur bofur bombur to library source code, we could then create a list of topics, where the information for what each of those topics is, is maintained outside the source code, and we include links to every module that had that topic tagged. So:

bifur -- modules related to the famous dwarf
links: <link1> <link2> ...

I see the value here in having a summary of topics that could help someone navigate, when they are not 100% sure what they need to look for. For example: “creating a directory under the current directory” – how do you find that in the code? (I know the answer, this is just an example).

2 Likes

I couldn’t help myself. I’ve created a little mockup of what a condensed “map” might look like:

http://ratfactor.com/zig/stdlib-docs.html

The entries that look real should take you to the correct source location when you click on them.

stdlib_sm

9 Likes

And maybe even links to corresponding ziglearn.org pages if available.

2 Likes

I like it. I would also add an even higher-level introduction to each “subdomain” of the standard library: std.math is for math functions, std.math.complex has complex numbers; std.os has OS-specific logic, std.os.linux has Linux-specific stuff, etc.

2 Likes

So I had a look at the article and I think you referring to this part

[…] What I disliked: the stdlib documentation is terrible. Everything I learned about directory scanning and file I/O – I got from github search results, which are also pretty scarce. […]

Can I ask where exactly you guys think the problem concerning the stdlib documentation is located:

  1. Is the code (types, functions) not documented enough with docstrings?
  2. Is the docstring system of Zig not sophisticated enough?
  3. Is the (html) presentation of the stdlib not functional (toc, html cross references inside the document)

Where is the main problem, where to start?

1 Like

A low effort solution for now could be a doc-search command for the compiler where it searches packages in scope for matching names along with doc which can be used as:

~ $ zig doc-search indexOf
std.mem.indexOfDiff - pub fn indexOfDiff(comptime T: type, a: []const T, b: []const T) ?usize
std.mem.indexOfSentinel - pub fn indexOfSentinel(comptime Elem: type, comptime sentinel: Elem, ptr: [*:sentinel]const Elem) usize
...

~ $ zig doc std.mem.indexOfDiff
Compares two slices and returns the index of the first inequality.
Returns null if the slices are equal.

~ $ zig doc-source std.mem.indexOfDiff
pub fn indexOfDiff(comptime T: type, a: []const T, b: []const T) ?usize {
    const shortest = math.min(a.len, b.len);
    if (a.ptr == b.ptr)
        return if (a.len == b.len) null else shortest;
    var index: usize = 0;
    while (index < shortest) : (index += 1) if (a[index] != b[index]) return index;
    return if (a.len == b.len) null else shortest;
}

~ $

Any packages are then just additional trees to traverse in th same manner and given by --pkg-begin lib lib/lib.zig --pkg-end as usual without the need for sema. A hoogle-style type search could also work with anytype matching all queries.

That would make “read the source” the most lazy thing you could do before proper documentation generation is decided upon.

4 Likes

The more I think about it, the more I like the principle of being able to lookup docs at the command line without having to invoke a browser. Kind of reminds me of the olden days when truly excellent documentation shipped with the language (like Perl).

For new users, I still think Web documentation is king, but for experienced Zig practitioners and CLI junkies, a zig subcommand or two like you’re suggesting would be really cool.

2 Likes

The most important feature IMHO is having the documentation exported (or easily exportable, anyway) into arbitrary formats so that you can use existing tools to browse the docs. These could include:

“Built-in documentation” sounds like a better fit for interpreted languages with a REPL like Python where you can use reflection to pull out docstrings and invoke doc(symbol) for just about anything. And even in that case, I find myself preferring the ease of opening https://docs.python.org/3/ in a browser so that I can keep multiple tabs open, etc…