[libcw-cvs] [CVS] Module src

[Carlo W. <li...@us...>]

CVSROOT    : /cvsroot/libcw
Module     : src
Commit time: 2002-01-24 22:36:13 UTC

Modified files:
     libcwd/documentation/symbols_intro.dox
     libcwd/include/libcw/debug.h libcwd/include/libcw/demangle.h

Log message:

demangle documentation fixes.
added intro for symbols chapter.

---------------------- diff included ----------------------
Index: src/libcwd/documentation/symbols_intro.dox
diff -u src/libcwd/documentation/symbols_intro.dox:1.2 src/libcwd/documentation/symbols_intro.dox:1.3
--- src/libcwd/documentation/symbols_intro.dox:1.2	Sat Dec 29 20:17:47 2001
+++ src/libcwd/documentation/symbols_intro.dox	Sun Feb 24 14:36:02 2002
@@ -6,7 +6,38 @@
 \page page_symbols_intro
 \ingroup chapter_symbols_intro
 
-Fix me: add text.
+Libcwd reads the symbol table of the application and of each
+of the linked object files upon initialization. 
+It then allows you to translate program counter addresses to
+function names, source file names and line numbers. 
+You can also print demangled names of any symbol or type, making
+the debug output better human readable. 
+
+<b>Example 1: printing the location that a function was called from:</b>
+
+\code
+#ifdef CWDEBUG
+// Get the location that we were called from.
+libcw::debug::location_ct location((char*)__builtin_return_address(0)
+    + libcw::debug::builtin_return_address_offset);
+// Demangle the function name of the location that we were called from.
+std::string demangled_function_name;
+libcw::debug::demangle_symbol(location.mangled_function_name(), demangled_function_name);
+// Print it.
+Dout(dc::notice, "This function was called from " << demangled_function_name << '(' << location << ')');
+#endif
+\endcode
+
+<b>Example 2: Printing the demangled name of the current (template) function:</b>
+
+\code
+// If we are in template Foo<TYPE>::f()
+Dout(dc::notice, "We are in Foo<" << type_info_of<TYPE>().demangled_name() << ">::f()");
+\endcode
+
+Note that calling \ref demangle_symbol costs cpu every time you call it, but using
+\ref type_info_of<> does not cost any cpu: the demangling is done once, during the
+initialization of libcwd; \ref type_info_of<> merely returns a static pointer.
 
 */
 
Index: src/libcwd/include/libcw/debug.h
diff -u src/libcwd/include/libcw/debug.h:1.45 src/libcwd/include/libcw/debug.h:1.46
--- src/libcwd/include/libcw/debug.h:1.45	Wed Feb 20 18:05:31 2002
+++ src/libcwd/include/libcw/debug.h	Sun Feb 24 14:36:03 2002
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/debug.h,v 1.45 2002/02/21 02:05:31 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/debug.h,v 1.46 2002/02/24 22:36:03 libcw Exp $
 //
 // Copyright (C) 2000 - 2002, by
 // 
@@ -228,6 +228,7 @@
 #include <libcw/macro_ForAllDebugChannels.h>
 #include <libcw/macro_ForAllDebugObjects.h>
 #include <libcw/private_environ.h>
+#include <libcw/demangle.h>
 
 // Include the inline functions.
 #include <libcw/class_channel.inl>		// Debug channels.
Index: src/libcwd/include/libcw/demangle.h
diff -u src/libcwd/include/libcw/demangle.h:1.7 src/libcwd/include/libcw/demangle.h:1.8
--- src/libcwd/include/libcw/demangle.h:1.7	Sun Feb 17 17:24:47 2002
+++ src/libcwd/include/libcw/demangle.h	Sun Feb 24 14:36:03 2002
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/demangle.h,v 1.7 2002/02/18 01:24:47 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/libcw/demangle.h,v 1.8 2002/02/24 22:36:03 libcw Exp $
 //
 // Copyright (C) 2000 - 2002, by
 // 
@@ -26,8 +26,13 @@
 namespace libcw {
   namespace debug {
 
+/** \addtogroup group_demangle */
+/** \{ */
+
 extern void demangle_type(char const* input, std::string& output);
 extern void demangle_symbol(char const* input, std::string& output);
+
+/** \} */
 
   } // namespace debug
 } // namespace libcw
----------------------- End of diff -----------------------