From ebc3286289111b5134032f03c29cb8a0ef7d5d34 Mon Sep 17 00:00:00 2001
From: anatoly techtonik <techtonik@gmail.com>
Date: Wed, 11 Nov 2015 21:44:46 +0300
Subject: Document SCons.Debug.caller_trace() behavior

---
 src/CHANGES.txt           | 12 +++++++++---
 src/engine/SCons/Debug.py | 11 +++++++++--
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index 02afa43..23fd49b 100644
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -4,17 +4,20 @@
 
                             Change Log
 
+
 RELEASE  VERSION/DATE TO BE FILLED IN LATER
 
   From John Doe:
-
     - Whatever John Doe did.
 
+  From Anatoly Techtonik:
+    - Document SCons.Debug.caller_trace() behavior.
+
 
 RELEASE 2.4.1 - Mon, 07 Nov 2015 10:37:21 -0700
 
   From Arfrever Frehtes Taifersar Arahesis:
-    - Fix for Bug # 2791 - Setup.py fails unnecessarily under Jython.
+    - Fix for Bug # 2791 - setup.py fails unnecessarily under Jython.
 
   From Dirk Baechle:
     - Fixed license of SVG titlepage files in the context of Debian
@@ -73,7 +76,6 @@ RELEASE 2.4.1 - Mon, 07 Nov 2015 10:37:21 -0700
     - Fix to swig tool - respect env['SWIG'] provided by user.
 
 
-
 RELEASE 2.4.0 - Mon, 21 Sep 2015 08:56:00 -0700
 
   From Dirk Baechle:
@@ -86,6 +88,8 @@ RELEASE 2.4.0 - Mon, 21 Sep 2015 08:56:00 -0700
   From Andrew Featherstone
     - Fixed typo in SWIGPATH description
 
+
+
 RELEASE 2.3.6 - Mon, 31 Jul 2015 14:35:03 -0700
 
   From Rob Smith:
@@ -379,6 +383,8 @@ RELEASE 2.3.0 - Mon, 02 Mar 2013 13:22:29 -0400
       Add builder InstallVersionedLib to create the required symlinks
       installing a versioned shared library.
 
+
+
 RELEASE 2.2.0 - Mon, 05 Aug 2012 15:37:48 +0000
 
   From dubcanada on Bitbucket:
diff --git a/src/engine/SCons/Debug.py b/src/engine/SCons/Debug.py
index b47c24c..9e520ff 100644
--- a/src/engine/SCons/Debug.py
+++ b/src/engine/SCons/Debug.py
@@ -1,7 +1,10 @@
 """SCons.Debug
 
 Code for debugging SCons internal things.  Shouldn't be
-needed by most users.
+needed by most users. Quick shortcuts:
+
+from SCons.Debug import caller_trace
+caller_trace()
 
 """
 
@@ -137,8 +140,12 @@ def caller_stack():
 caller_bases = {}
 caller_dicts = {}
 
-# trace a caller's stack
 def caller_trace(back=0):
+    """
+    Trace caller stack and save info into global dicts, which
+    are printed automatically at the end of SCons execution.
+    """
+    global caller_bases, caller_dicts
     import traceback
     tb = traceback.extract_stack(limit=3+back)
     tb.reverse()
-- 
cgit v0.12