Feature Request: Automatic Documentation Generation for Constraints

[aszepieniec]

Currently, the constraints are described in 3 places:

• in the specification, in human-readable form;
• in the specification, in circuit form;
• in the code, in circuit form.

Downsides: We need at least 2 equivalences between pairs of forms, which is confusing for humans and exposes a larger than necessary vulnerability surface. Furthermore, the various forms are in disparate locations, compounding the problem.

Proposed solution: Let's embed the human-readable form in comments in the source code, and then generate the documentation (both human-readable and circuit forms) from the comments and subsequent code using a script. With this approach, there is one source of truth: the code. But to verify that the code is correct is suffices to read the documentation and verify the human-readable description against the nicely rendered circuit form in the browser.

[jan-ferdinand]

I like the idea and will investigate tools to help the endeavor. Writing such tools ourselves currently seems like too much effort for the benefit.