debuginfo: Added some documentation of source location management.

Author: michaelwoerister

src/librustc/middle/trans/debuginfo.rs

@@ -85,6 +85,43 @@ continuation, storing all state needed to continue traversal at the type members
 been registered with the cache. (This implementation approach might be a tad over-engineered and
 may change in the future)
 
+
+## Source Locations and Line Information
+In addition to data type descriptions the debugging information must also allow to map machine code
+locations back to source code locations in order to be useful. This functionality is also handled in
+this module. The following functions allow to control source mappings:
+
++ set_source_location()
++ clear_source_location()
++ start_emitting_source_locations()
+
+`set_source_location()` allows to set the current source location. All IR instructions created after
+a call to this function will be linked to the given source location, until another location is
+specified with `set_source_location()` or the source location is cleared with
+`clear_source_location()`. In the later case, subsequent IR instruction will not be linked to any
+source location. As you can see, this is a stateful API (mimicking the one in LLVM), so be careful
+with source locations set by previous calls. It's probably best to not rely on any specific state
+being present at a given point in code.
+
+One topic that deserves some extra attention is *function prologues*. At the beginning of a
+function's machine code there are typically a few instructions for loading argument values into
+allocas and checking if there's enough stack space for the function to execute. This *prologue* is
+not visible in the source code and LLVM puts a special PROLOGUE END marker into the line table at
+the first non-prologue instruction of the function. In order to find out where the prologue ends,
+LLVM looks for the first instruction in the function body that is linked to a source location. So,
+when generating prologue instructions we have to make sure that we don't emit source location
+information until the 'real' function body begins. For this reason, source location emission is
+disabled by default for any new function being translated and is only activated after a call to the
+third function from the list above, `start_emitting_source_locations()`. This function should be
+called right before regularly starting to translate the top-level block of the given function.
+
+There is one exception to the above rule: `llvm.dbg.declare` instruction must be linked to the
+source location of the variable being declared. For function parameters these `llvm.dbg.declare`
+instructions typically occur in the middle of the prologue, however, they are ignored by LLVM's
+prologue detection. The `create_argument_metadata()` and related functions take care of linking the
+`llvm.dbg.declare` instructions to the correct source locations even while source location emission
+is still disabled, so there is no need to do anything special with source location handling here.
+
 */