exception (__verbose_terminate_handler): Point to docs.

2002-04-01  Phil Edwards  <pme@gcc.gnu.org>

	* libsupc++/exception (__verbose_terminate_handler):  Point to docs.
	* docs/doxygen/doxygroups.cc:  Doxygen hooks for abi::__cxa_demangle.
	* docs/html/18_support/howto.html:  Document the demangler.
	* docs/html/17_intro/howto.html:  And link to it.

	* docs/doxygen/mainpage.html:  Describe user-vs-maintainer docs.
	* docs/doxygen/run_doxygen:  Print user-vs-maintainer.

From-SVN: r51730

5 files changed, 154 insertions, 9 deletions

diff --git a/libstdc++-v3/docs/doxygen/doxygroups.cc b/libstdc++-v3/docs/doxygen/doxygroups.cc
index c6139f3..da71879 100644
--- a/libstdc++-v3/docs/doxygen/doxygroups.cc
+++ b/libstdc++-v3/docs/doxygen/doxygroups.cc
@@ -1,4 +1,3 @@
-
 /*
    Copyright (C) 2001, 2002 Free Software Foundation, Inc.
    See license.html for license.
@@ -7,6 +6,11 @@
    source headers themselves.  It is a ".cc" file for the sole cheesy reason
    that it triggers many different text editors into doing Nice Things when
    typing comments.  However, it is mentioned nowhere except the *cfg.in files.
+
+   Some actual code (declarations) is exposed here, but no compiler ever
+   sees it.  The decls must be visible to doxygen, and sometimes their real
+   declarations are not visible, or not visible in a way we want.
+
    Pieces separated by '// //' lines will usually not be presented to the
    user on the same page.
 */
@@ -112,4 +116,69 @@ All associative containers must meet certain requirements, summarized in
 */
 
 // // // // // // // // // // // // // // // // // // // // // // // //
+/** @namespace abi
+ *  @brief The cross-vendor C++ Application Binary Interface.
+ *
+ *  A brief overview of an ABI is given in the libstdc++-v3 FAQ, question
+ *  5.8 (you may have a copy of the FAQ locally, or you can view the online
+ *  version at http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html#5_8).
+ *
+ *  GCC subscribes to a relatively-new cross-vendor ABI for C++, sometimes
+ *  called the IA64 ABI because it happens to be the native ABI for that
+ *  platform.  It is summarized at http://www.codesourcery.com/cxx-abi/
+ *  along with the current specification.
+ *
+ *  For users of GCC 3.x, entry points are available in <cxxabi.h>, which notes,
+ *  <em>"It is not normally necessary for user programs to include this header,
+ *  or use the entry points directly.  However, this header is available
+ *  should that be needed."</em>
+*/
+
+namespace abi {
+/**
+@brief New ABI-mandated entry point in the C++ runtime library for demangling.
+
+@param mangled_name A NUL-terminated character string containing the name
+                    to be demangled.
+
+@param output_buffer A region of memory, allocated with malloc, of
+                     @a *length bytes, into which the demangled name
+                     is stored.  If @a output_buffer is not long enough,
+                     it is expanded using realloc.  @a output_buffer may
+                     instead be NULL; in that case, the demangled name is
+                     placed in a region of memory allocated with malloc.
+
+@param length If @a length is non-NULL, the length of the buffer containing
+              the demangled name is placed in @a *length.
+
+@param status @a *status is set to one of the following values:
+              -   0: The demangling operation succeeded.
+              -  -1: A memory allocation failiure occurred.
+              -  -2: @a mangled_name is not a valid name under the C++ ABI
+                     mangling rules.
+              -  -3: One of the arguments is invalid.
+
+@return A pointer to the start of the NUL-terminated demangled name, or NULL
+        if the demangling fails.  The caller is responsible for deallocating
+        this memory using @c free.
+
+
+The demagling is performed using the C++ ABI mangling rules, with
+GNU extensions.  For example, this function is used
+in __gnu_cxx::__verbose_terminate_handler.  See
+http://gcc.gnu.org/onlinedocs/libstdc++/18_support/howto.html#5 for other
+examples of use.
+
+@note The same demangling functionality is available via libiberty 
+(@c <libiberty/demangle.h> and @c libiberty.a) in GCC 3.1 and later, but that
+requires explicit installation (@c --enable-install-libiberty) and uses a
+different API, although the ABI is unchanged.
+*/
+char* __cxa_demangle (const char* mangled_name, char* output_buffer,
+                      size_t* length, int* status);
+} // namespace abi
+
+// // // // // // // // // // // // // // // // // // // // // // // //
+
+// vim:et:noai:
 
diff --git a/libstdc++-v3/docs/doxygen/mainpage.html b/libstdc++-v3/docs/doxygen/mainpage.html
index 431344b..ecfa649 100644
--- a/libstdc++-v3/docs/doxygen/mainpage.html
+++ b/libstdc++-v3/docs/doxygen/mainpage.html
@@ -25,7 +25,7 @@
 
 <h2> Documentation Overview </h2>
 
-<p class="smallertext">Generated 2002-03-27.</p>
+<p class="smallertext">@LEVEL@-level docs, generated @DATE@.</p>
 
 <p>There are two types of documentation for libstdc++-v3.  One is the
    distribution documentation, which can be read online at
@@ -35,7 +35,14 @@
 </p>
 
 <p>The other type is the source documentation, of which this is the first page.
-   Here are quick links to the pages which we seem to use the most; a full
+   Both &quot;user-level&quot; and &quot;maintainer-level&quot; source
+   documentation is produced:  user-level docs are for the users of this
+   library.  The maint-level docs are for those interested in the underlying
+   workings of the library; they include all the user-level docs plus
+   additional notes and additional classes/functions/etc.
+</p>
+
+<p>Here are quick links to the pages which we seem to use the most; a full
    index is at the bottom:
    <!-- Keep this in sync with below. -->
    <ul>
@@ -48,10 +55,10 @@
 
 <h2> Generating this file </h2>
 <p>These HTML pages are automatically generated, along with the man pages.
-   The Makefile rule <code> 'make
-   doxygen' </code> in the libstdc++-v3 build directory generates these pages
-   using a tool called, appropriately enough, Doxygen.  To learn more about
-   Doxygen, take a look at
+   The Makefile rules <code> 'make doxygen' </code> and
+   <code> 'make doxygen-maint' </code> in the libstdc++-v3 build directory
+   generates these pages using a tool called, appropriately enough, Doxygen.
+   To learn more about Doxygen, take a look at
    <a href="http://www.doxygen.org/">
    <!-- snagged from the generated page -->
    <img src="doxygen.gif" alt="the Doxygen homepage"
diff --git a/libstdc++-v3/docs/doxygen/run_doxygen b/libstdc++-v3/docs/doxygen/run_doxygen
index 7b3b7f5..92cb882 100644
--- a/libstdc++-v3/docs/doxygen/run_doxygen
+++ b/libstdc++-v3/docs/doxygen/run_doxygen
@@ -95,6 +95,7 @@ outdir=unset
 do_html=no
 do_man=no
 enabled_sections=
+DATEtext=`date '+%Y-%m-%d'`
 
 parse_options $*
 find_doxygen
@@ -107,9 +108,11 @@ fi
 
 case x"$mode" in
     xuser)           do_html=yes
+                     LEVELtext='User'
                      ;;
     xmaint)          do_html=yes
                      enabled_sections=maint
+                     LEVELtext='Maintainer'
                      ;;
     xman)            do_man=yes
                      ;;
@@ -147,7 +150,9 @@ set -e
 set +e
 
 test $do_html = yes && {
-    cp ${srcdir}/docs/doxygen/mainpage.html ${outdir}/html_${mode}/index.html
+    sed -e "s=@LEVEL@=${LEVELtext}=" \
+        -e "s=@DATE@=${DATEtext}=" \
+        ${srcdir}/docs/doxygen/mainpage.html > ${outdir}/html_${mode}/index.html
     cp ${srcdir}/docs/doxygen/tables.html ${outdir}/html_${mode}/tables.html
     echo ::
     echo :: HTML pages begin with
diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html
index 914213a..21f83f9 100644
--- a/libstdc++-v3/docs/html/17_intro/howto.html
+++ b/libstdc++-v3/docs/html/17_intro/howto.html
@@ -205,7 +205,8 @@
       classes publicly derived from it, simply returns the name of the
       class.  But they are the <em>mangled</em> names; you will need to call
       <code>c++filt</code> and pass the names as command-line parameters to
-      demangle them.
+      demangle them, or call a
+      <a href="../18_support/howto.html#5">runtime demangler function</a>.
       (The classes in <code>&lt;stdexcept&gt;</code> have constructors which
       require an argument to use later for <code>what()</code> calls, so the
       question does not arise in most user-defined exceptions.)
diff --git a/libstdc++-v3/docs/html/18_support/howto.html b/libstdc++-v3/docs/html/18_support/howto.html
index 13adbfd..10c74a9 100644
--- a/libstdc++-v3/docs/html/18_support/howto.html
+++ b/libstdc++-v3/docs/html/18_support/howto.html
@@ -31,6 +31,7 @@
    <li><a href="#2">Implementation properties</a>
    <li><a href="#3">Start and Termination</a>
    <li><a href="#4">Dynamic memory management</a>
+   <li><a href="#5">RTTI, the ABI, and demangling</a>
 </ul>
 
 <hr>
@@ -255,6 +256,68 @@
       <a href="../faq/index.html">to the FAQ</a>.
    </p>
 
+<hr>
+<h2><a name="5">RTTI, the ABI, and demangling</a></h2>
+   <p>If you have read the <a href="../documentation.html#4">source
+      documentation</a> for <code> namespace abi </code> then you are aware
+      of the cross-vendor C++ ABI which we use.  One of the exposed
+      functions is the one which we use for demangling in programs like
+      <code>c++filt</code>, and you can use it yourself as well.
+   </p>
+   <p>(The function itself might use different demanglers, but that's the
+      whole point of abstract interfaces.  If we change the implementation,
+      you won't notice.)
+   </p>
+   <p>Probably the only times you'll be interested in demangling at runtime
+      are when you're seeing <code>typeid</code> strings in RTTI, or when
+      you're handling the runtime-support exception classes.  For example:
+      <pre>
+#include &lt;exception&gt;
+#include &lt;iostream&gt;
+#include &lt;cxxabi.h&gt;
+
+struct empty { };
+
+template &lt;typename T, int N&gt;
+  struct bar { };
+
+
+int main()
+{
+  int     status;
+  char   *realname;
+
+  // exception classes not in &lt;stdexcept&gt;, thrown by the implementation
+  // instead of the user
+  std::bad_exception  e;
+  realname = abi::__cxa_demangle(e.what(), 0, 0, &amp;status);
+  std::cout &lt;&lt; e.what() &lt;&lt; "\t=&gt; " &lt;&lt; realname &lt;&lt; "\t: " &lt;&lt; status &lt;&lt; '\n';
+  free(realname);
+
+
+  // typeid
+  bar&lt;empty,17&gt;          u;
+  const std::type_info  &amp;ti = typeid(u);
+
+  realname = abi::__cxa_demangle(ti.name(), 0, 0, &amp;status);
+  std::cout &lt;&lt; ti.name() &lt;&lt; "\t=&gt; " &lt;&lt; realname &lt;&lt; "\t: " &lt;&lt; status &lt;&lt; '\n';
+  free(realname);
+
+  return 0;
+}</pre></p>
+   <p>With GCC 3.1 and later, this prints<pre>
+      St13bad_exception       =&gt; std::bad_exception   : 0
+      3barI5emptyLi17EE       =&gt; bar&lt;empty, 17&gt;       : 0</pre>
+   </p>
+   <p>The demangler interface is described in the source documentation
+      linked to above.  It is actually written in C, so you don't need to
+      be writing C++ in order to demangle C++.  (That also means we have to
+      use crummy memory management facilities, so don't forget to free()
+      the returned char array.)
+   </p>
+   <p>Return <a href="#top">to top of page</a> or
+      <a href="../faq/index.html">to the FAQ</a>.
+   </p>
 
 
 <!-- ####################################################### -->