developer notes

docs/design-notes.adoc

@@ -0,0 +1,14 @@
+Design Notes
+===========
+
+AST Traversal
+~~~~~~~~~~~~~
+During the AST traversal stage, the complete AST (generated by the clang frontend) is walked beginning with the root `TranslationUnitDecl` node. It is during this stage that USRs (universal symbol references) are generated and hashed with SHA1 to form the 160 bit `SymbolID` for an entity. With the exception of built-in types, *all* entities referenced in the corpus will be traversed and be assigned a `SymbolID`; including those from the standard library. This is necessary to generate the full interface for user-defined types.
+
+Bitcode
+~~~~~~~
+AST traversal is performed in parallel on a per-translation-unit basis. To maximize the size of the code base MrDox is capable of processing, `Info` types generated during traversal are serialized to a compressed bitcode representation. Once AST traversal is complete for all translation units, the bitcode is deserialized back into `Info` types, and then merged to form the corpus. The merging step is necessary as there may be multiple identical definitions of the same entity (e.g. for class types, templates, inline functions, etc), as well as functions declared in one translation unit & defined in another.
+
+The Corpus
+~~~~~~~~~~
+After AST traversal and `Info` merging, the result is stored as a map of `Info`s indexed by their respective `SymbolID`s. Documentation generators may traverse this structure by calling `Corpus::traverse` with a `Corpus::Visitor` derived visitor and the `SymbolID` of the entity to visit (e.g. the global namespace).