From 310478521be031afd7d972d29895c75ad0e82a15 Mon Sep 17 00:00:00 2001
From: Davis King <davis@dlib.net>
Date: Thu, 15 May 2008 01:06:57 +0000
Subject: [PATCH] updated the docs

--HG--
extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%402238
---
 docs/docs/metaprogramming.xml | 60 +++++++++++++++++++++++++++++++++++
 docs/docs/release_notes.xml   | 16 +++++++++-
 docs/docs/term_index.xml      |  5 +++
 3 files changed, 80 insertions(+), 1 deletion(-)

diff --git a/docs/docs/metaprogramming.xml b/docs/docs/metaprogramming.xml
index 8852f39f8..2c10ecf8b 100644
--- a/docs/docs/metaprogramming.xml
+++ b/docs/docs/metaprogramming.xml
@@ -47,6 +47,9 @@
       <section>
          <name>Global Functions</name>
          <item>DLIB_ASSERT</item> 
+         <item>DLIB_STACK_TRACE</item> 
+         <item>DLIB_STACK_TRACE_NAMED</item> 
+         <item>get_stack_trace</item> 
          <item>DLIB_CASSERT</item> 
          <item>COMPILE_TIME_ASSERT</item> 
          <item>ASSERT_ARE_SAME_TYPE</item> 
@@ -337,6 +340,63 @@
       </component>
             
             
+   <!-- ************************************************************************* -->
+      
+      <component>
+         <name>DLIB_STACK_TRACE</name>
+         <file>dlib/assert.h</file>
+         <spec_file>dlib/stack_trace.h</spec_file>
+         <description>
+         <p>
+            This is a preprocessor macro that allows you to tag a function so 
+            that dlib will keep track of it in a function call stack.  That is,
+            you will be able to see a stack trace by calling <a href="#get_stack_trace">get_stack_trace</a>
+            if you put this macro at the top of your functions.
+         </p>
+         <p>
+            This macro is only enabled if DLIB_ENABLE_STACK_TRACE is defined.  If it isn't defined then
+            this macro doesn't do anything.  Also note that when this macro is defined it will
+            cause <a href="#DLIB_ASSERT">DLIB_ASSERT</a> and <a href="#DLIB_CASSERT">DLIB_CASSERT</a>
+            to include a stack trace in their error messages.
+         </p>
+         </description>
+                                 
+      </component>
+            
+            
+   <!-- ************************************************************************* -->
+      
+      <component>
+         <name>DLIB_STACK_TRACE_NAMED</name>
+         <file>dlib/assert.h</file>
+         <spec_file>dlib/stack_trace.h</spec_file>
+         <description>
+            This is a preprocessor macro just like <a href="#DLIB_STACK_TRACE">DLIB_STACK_TRACE</a>
+            except that it allows you to supply your own string to use as the function name
+            in the stack trace instead of the one deduced by DLIB_STACK_TRACE.
+            <p>
+               This macro is only enabled if DLIB_ENABLE_STACK_TRACE is defined.  
+            </p>
+         </description>
+                                 
+      </component>
+            
+   <!-- ************************************************************************* -->
+
+      <component>
+         <name>get_stack_trace</name>
+         <file>dlib/assert.h</file>
+         <spec_file>dlib/stack_trace.h</spec_file>
+         <description>
+            This function allows you to query the current stack trace.
+            <p>
+               This macro is only enabled if DLIB_ENABLE_STACK_TRACE is defined.  
+            </p>
+         </description>
+                                 
+      </component>
+            
+            
    <!-- ************************************************************************* -->
       
       <component>
diff --git a/docs/docs/release_notes.xml b/docs/docs/release_notes.xml
index 3fe7f5994..068acb656 100644
--- a/docs/docs/release_notes.xml
+++ b/docs/docs/release_notes.xml
@@ -11,6 +11,20 @@
 <!-- *******************************************************************************  -->
 
 <current>
+New Stuff:
+   - Added some macros that allow dlib to create a stack trace
+
+Non-Backwards Compatible Changes:
+
+Bug fixes:
+
+Other:
+
+</current>
+
+<!-- *******************************************************************************  -->
+
+<old name="17.4" date="May 12, 2008">
 New Stuff:
    - Added an implementation of the kernel recursive least squares algorithm
 
@@ -29,7 +43,7 @@ Other:
    - Added some stuff to make people get a really obvious error message
      when they set up the include path incorrectly.
 
-</current>
+</old>
 
 <!-- *******************************************************************************  -->
 
diff --git a/docs/docs/term_index.xml b/docs/docs/term_index.xml
index 170341ac6..367424d87 100644
--- a/docs/docs/term_index.xml
+++ b/docs/docs/term_index.xml
@@ -510,6 +510,11 @@
 
 
 
+         <term link="metaprogramming.html#DLIB_STACK_TRACE" name="DLIB_ENABLE_STACK_TRACE"/>
+         <term link="metaprogramming.html#DLIB_STACK_TRACE" name="DLIB_STACK_TRACE"/>
+         <term link="metaprogramming.html#DLIB_STACK_TRACE" name="Stack Trace"/>
+         <term link="metaprogramming.html#DLIB_STACK_TRACE_NAMED" name="DLIB_STACK_TRACE_NAMED"/>
+         <term link="metaprogramming.html#get_stack_trace" name="get_stack_trace"/>
 
          <term link="metaprogramming.html#unsigned_type" name="unsigned_type"/>
          <term link="metaprogramming.html#DLIB_ASSERT" name="DLIB_ASSERT"/>