feat: Doxygen init

barretenberg/README.md

@@ -250,6 +250,70 @@ CI will automatically run integration tests against Aztec's circuits which live
 
 When working on a PR, you may want to point this file to a different Aztec branch or commit, but then it should probably be pointed back to master before merging.
 
+### 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.
+
 ### Testing locally in docker
 
 A common issue that arises is that our CI system has a different compiler version e.g. namely for GCC. If you need to mimic the CI operating system locally you can use bootstrap_docker.sh or run dockerfiles directly. However, there is a more efficient workflow for iterative development:
@@ -260,4 +324,5 @@ cd barretenberg/cpp
 mv build build-native # your native build folders are mounted, but will not work! have to clear them
 cmake --preset gcc ;  cmake --build build
 ```
+
 This will allow you to rebuild as efficiently as if you were running native code, and not have to see a full compile cycle.

barretenberg/cpp/.gitignore

@@ -1,5 +1,6 @@
 .cache/
 build*/
+.doxygen/
 src/wasi-sdk-*
 src/barretenberg/proof_system/proving_key/fixtures
 src/barretenberg/rollup/proofs/*/fixtures

barretenberg/cpp/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
+$PWD/.doxygen/bin/doxygen docs/Doxyfile