diff options
| author | Phil Edwards <pme@gcc.gnu.org> | 2002-04-02 02:07:22 +0000 |
|---|---|---|
| committer | Phil Edwards <pme@gcc.gnu.org> | 2002-04-02 02:07:22 +0000 |
| commit | efe44c60eb50355fe2c87d0765b137a7f886d2fa (patch) | |
| tree | ebb016f14c2486b31257b6dfef4e84895d124eab /libstdc++-v3/docs/doxygen | |
| parent | b88a94c6034309e1ac64fc4c71db44f5dc474b18 (diff) | |
| download | gcc-efe44c60eb50355fe2c87d0765b137a7f886d2fa.zip gcc-efe44c60eb50355fe2c87d0765b137a7f886d2fa.tar.gz gcc-efe44c60eb50355fe2c87d0765b137a7f886d2fa.tar.bz2 | |
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
Diffstat (limited to 'libstdc++-v3/docs/doxygen')
| -rw-r--r-- | libstdc++-v3/docs/doxygen/doxygroups.cc | 71 | ||||
| -rw-r--r-- | libstdc++-v3/docs/doxygen/mainpage.html | 19 | ||||
| -rw-r--r-- | libstdc++-v3/docs/doxygen/run_doxygen | 7 |
3 files changed, 89 insertions, 8 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 "user-level" and "maintainer-level" 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 |