chore: Add doxygen

.gitignore

@@ -4,5 +4,7 @@ node_modules
 .yarn/install-state.gz
 ts/dest
 .tsbuildinfo
+.doxygen/*
+doxydoc/*
 .idea
 cmake-build-debug

README.md

@@ -1,3 +1,4 @@
+\page README README
 ## Barretenberg, an optimized elliptic curve library for the bn128 curve, and PLONK SNARK prover
 
 **This code is highly experimental, use at your own risk!**
@@ -201,6 +202,71 @@ Alternatively you can build separate test binaries, e.g. honk_tests or numeric_t
 
 A default configuration for VS Code is provided by the file [`barretenberg.code-workspace`](barretenberg.code-workspace). These settings can be overridden by placing configuration files in `.vscode/`.
 
+### Doxygen
+
+An alternative might be retrofitting https://www.cryptologie.net/article/553/the-code-is-the-specification-introducing-cargo-spec/ to our needs.
+
+Installation: run boostrap_doxygen.sh.
+
+The file ./Doxyfile is a config for doxygen. There are tons of options. For example, you can generate very cool but often uselessly huge diagrams by setting `HAVE_DOT` to `YES`.
+
+To generate the documentation: `doxygen Doxyfile`
+
+To browse the generated documentation, a good starting point is: ./doxydoc/html/index.html
+
+Reference: http://web.evolbio.mpg.de/~boettcher//other/2016/creating_source_graph.html
+
+#### Notes
+
+All words that contain a dot (.) that is not the last character in the word are considered to be file names. If the word is indeed the name of a documented input file, a link will automatically be created to the documentation of that file.
+
+Large delimiters (`\big(`, `\left(`, also the `cases` environment) are not natively supported.
+
+
+The purpose of this documentation: 
+  - The goal of this documentation is to be self-contained and authoritative.
+  - It cannot be used to record speculations or planned developments. It is documentation of what's implemented.
+  - It should always be accurate.
+  - It should use notation that facilitates the documentation being accurate.
+  - It should be "direct" in the sense of the reflecting the code. It should not use unnecessary abstractions or notation that that is unnatural to use in code comments.
+  - It should remove ambiguity rather than to add it. It is not just another HackMD document.
+  - It should _not depend_ on external references except for published or widely-used papers (PlonK; Honk; Bulletproofs). It should not reference things published on HackMD.
+  - It may _make_ external references to publicly-available sources, but that should be to resolve potential confusions that a user might face when reconciling differences between sources.
+
+
+There is a global file barretenberg/spec/macros.tex that allows for using latex macros. This is convenient, it encourages standarization of notation across the repo, and it also enables changing that notation with minimal footprint in the diffs.
+
+Grouping can be used to make pages that list classes or pages together even though they're not grouped together in the code.
+
+Call graph and caller graph are different
+
+
+"Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a /*! \file */ or a ..."
+
+`@example` could be useful. There is a special toolbar icon for examples
+
+useful: `@attention`, `@bug`, `@deprecated` (maintains a deprecated list page), `@note`, `@anchor` + `@ref`, `@tableofcontents`, `@details`?, `@copybrief` and `@copydetails`
+
+[@dontinclude](https://www.doxygen.nl/manual/commands.html#cmddontinclude) could possibly be useful in special situations but it's overly manual to be a reasonable general solution to stitching things together, unfortunately.
+
+It to be relatively easy to include hand-made dot diagrams in documentation.
+
+There is support for creating message sequence charts as in: https://www.mcternan.me.uk//mscgen/ and more general kinds of diagrams as in https://plantuml.com/state-diagram
+
+TODO:
+  - Control tree view alla [SO-28938063](https://stackoverflow.com/questions/28938063/customize-treeview-in-doxygen)?
+  - Use `@test` tag
+  - Use `@todo` tag
+  - Use `@deprecated` tag
+  - Investigate warnings when using `*_impl.hpp` implementations.
+  - use testing namespace everywhere (e.g. in plonk composer tests) to prevent tons of useless test documentation from being created at in general namespace level like plonk
+
+The VS Code extension oijaz.unicode-latex is convenient for parsing latex to unicode, e.g., `\gamma` to becomes `γ`, and this can make latex-heavy comments much easier to parse (`\gamma` seems to render as well as `γ`, to my surprise).
+
+The `@details` tag is 'greedy' int the sense that it wants to include lots of data specified by other tags. As far as I can tell, the most robust strategy for putting documentation with code is to make the `@details` part of the leading code (the one coming before the class/function/whatever definiton) and then putting unwanted stuff inside the function body.
+
+I recall seeing a way to extract parts of comments that are inside function bodies. Not sure a good application of this, though, sounds fidgety.
+
 ### Integration tests with Aztec Circuits
 
 CI will automatically run integration tests against Aztec's circuits which live [here](https://github.com/AztecProtocol/aztec-packages/tree/master/circuits). To change which Aztec branch or commit for CI to test against, modify [`.aztec-packages-commit`](./cpp/.aztec-packages-commit).

biblio.bib

@@ -0,0 +1,17 @@
+@misc{PlonK,
+      author = {Ariel Gabizon and Zachary J.  Williamson and Oana Ciobotaru},
+      title = {PLONK: Permutations over Lagrange-bases for Oecumenical Noninteractive arguments of Knowledge},
+      howpublished = {Cryptology ePrint Archive, Paper 2019/953},
+      year = {2019},
+      note = {\url{https://eprint.iacr.org/2019/953}},
+      url = {https://eprint.iacr.org/2019/953}
+}
+
+@misc{PlonKVIP,
+      author = {Ariel Gabizon and Zachary J.  Williamson},
+      title = {PLONK: VIP Edition},
+      howpublished = {GitHub},
+      year = {2020},
+      note = {\url{https://github.com/AztecProtocol/plonk-with-lookups-private/blob/new-stuff/PLONK-VIP%20edition.pdf}},
+      url = {https://github.com/AztecProtocol/plonk-with-lookups-private/blob/new-stuff/PLONK-VIP%20edition.pdf}
+}

bootstrap_doxygen.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+set -ev
+
+curl -SL https://github.com/doxygen/doxygen/releases/download/Release_1_9_6/doxygen-1.9.6.linux.bin.tar.gz -o doxygen.bin.tar.gz
+tar -xvf doxygen.bin.tar.gz && mv doxygen-1.9.6 .doxygen
+rm doxygen.bin.tar.gz
+export PATH=$PWD/.doxygen/bin:$PATH
+doxygen cpp/Doxyfile