1 of 8

Naming convention

​

​

  • Autodoc
    • the system that automatically generates docs from source code
  • Autodocs
    • An instance of docs generated by the Autodoc system

​

2 of 8

High level design

  • Output is a single page application
    • Supports search
    • Navigation is instant & no network requests needed
      • Trivially works in offline mode
    • Code information is stored as data that gets rendered on demand
      • Needed for search
      • Keeps memory requirements low
  • This means that the "backend" (ie the Zig compiler) must produce a JSON payload for the "frontend" (ie a JS script) to consume.

​

3 of 8

Features

Everything that stage1 Autodoc does plus

  • Improve on some of the information displayed
    • "internal" mode that also displays private decls
    • don't make unanalyzed functions / types disappear
  • "Sources" section that displays syntax-highlighted Zig files
  • "Guides" section that displays rendered markdown files

​

​

4 of 8

Implementation architecture

  • Base Autodoc work on ZIR data, analyze what's trivial, resolve complex stuff to "ComptimeExpr".
    • Autodoc is invoked between astgen and sema
    • We call Autodoc.generateZirData on the root file
    • By analyzing the top level struct we then reach every file
  • After sema is done, take "ComptimeExpr"s and see if Sema happened to do the analysis for us. If so, update doc data with this extra information.
    • This second step is not yet implemented

​

5 of 8

Pros, cons and open questions

  • ZIR lets us
    • see code that won't go through semantic analysis
    • perform our own kind of analysis that cares about things that sema might not care about (eg preserving decl names and paths)
  • But
    • code that hasn't gone through sema might be completely borked
    • we have to implement our own analysis, which means reimplementing a toy version of sema
  • How should the ultimate version of Autodoc look like?

​

6 of 8

Implementation status

  • Working on getting back to feature parity with stage1 Autodoc
  • Next goal is to support enough of the language to build the stdlib
    • That's actually not impossibly hard, Autodoc is only concerned with the top-level context where decls are created.
    • We can already build `std.ascii`
  • Lots of things need more polish
    • Sometimes I cut corners
    • Sometimes I didn't fully understand the complexity behind a language construct

​

7 of 8

How to contribute

  • All work is currently done in ziglang/autodocs-zir
    • Two main files being changed:
      • src/Autodoc.zig
      • lib/std/special/docs/main.js
  • Read comments in Autodoc.zig!
  • Run autodoc on a tiny project / single stdlib file
    • zig2 build-obj foo.zig -femit-docs
  • Resolve any TODO panic or inspect the output and add some polish
    • WARNING: polish might require touching javascript code

​

8 of 8

Tips and tricks

  • Use ast-check -t to look at the ZIR
    • This can help you produce a reduced test case if needed.
  • Do you have experience with sema?
    • NO: great, autodoc can be a smooth way of getting introduced to the general concept
    • YES: great, you might help us reinvent the wheel the right way
      • Although be aware of unique concepts in Autodoc
  • In theory *all* panics should lead you to a TODO.
    • Either in their message or by a comment on the offending line (eg yolo union accesses).
  • Ping me for help understanding what the code is doing

​