Added overview of the debuginfo module at the beginning of debuginfo.rs.

src/librustc/middle/trans/debuginfo.rs

@@ -8,6 +8,32 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+/*!
+# Debug Info Module
+
+This module serves the purpose of generating debug symbols. We use LLVM's 
+[source level debugging](http://llvm.org/docs/SourceLevelDebugging.html) features for generating
+the debug information. The general principle is this:
+
+Given the right metadata in the LLVM IR, the LLVM code generator is able to create DWARF debug 
+symbols for the given code. The [metadata](http://llvm.org/docs/LangRef.html#metadata-type) is 
+structured much like DWARF *debugging information entries* (DIE), representing type information 
+such as datatype layout, function signatures, block layout, variable location and scope information,
+etc. It is the purpose of this module to generate correct metadata and insert it into the LLVM IR.
+
+As the exact format of metadata trees may change between different LLVM versions, we now use LLVM
+[DIBuilder](http://llvm.org/docs/doxygen/html/classllvm_1_1DIBuilder.html) which to create metadata
+where possible. This will hopefully ease the adaption of this module to future LLVM versions. 
+
+The public API of the module is a set of functions that will insert the correct metadata into the 
+LLVM IR when called with the right parameters. The module is thus driven from an outside client with
+function like `debuginfo::create_local_var(bcx: block, local: @ast::local)`.
+
+Internally the module will try to reuse already created metadata by utilizing a cache. All private
+state used by the module is stored within a DebugContext struct, which in turn is contained in the
+CrateContext.
+*/
+
 use core::prelude::*;
 
 use driver::session;