---

yaml
---
r: 63495
b: refs/heads/snap-stage3
c: 5d5311d
h: refs/heads/master
i:
  63493: 98ffbac
  63491: 129aa8f
  63487: 70fb7a9
v: v3

Author: michaelwoerister

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: 2d28d645422c1617be58c8ca7ad9a457264ca850
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: 7375e94289622663ba9976e2702a4008cd0aad1a
+refs/heads/snap-stage3: 5d5311dc74b2bce19a754538dfd3c849e8c989ed
 refs/heads/try: 7b78b52e602bb3ea8174f9b2006bff3315f03ef9
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/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;