From 5db584dfc89dd133d6765ed37c1e4fbc9f9372c5 Mon Sep 17 00:00:00 2001 From: guido Date: Sun, 11 Jan 2004 12:31:06 +0000 Subject: [PATCH] more changes for Doxygen git-svn-id: https://svn.dealii.org/trunk@8304 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/doc/doxygen/Makefile | 2 +- .../doc/doxygen/headers/base/instantiations.h | 105 ++++++++++++++++++ 2 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 deal.II/doc/doxygen/headers/base/instantiations.h diff --git a/deal.II/doc/doxygen/Makefile b/deal.II/doc/doxygen/Makefile index 08971cba74..7d71b98c7c 100644 --- a/deal.II/doc/doxygen/Makefile +++ b/deal.II/doc/doxygen/Makefile @@ -6,7 +6,7 @@ html: deal.tag private: - perl -pi -e 's/(EXTRACT_PRIVATE\s*=\s*)NO/$$1YES/' options.dox + perl -pi -e 's/(EXTRACT_PRIVATE\s*=\s*)NO/$$1YES/;s/(INTERNAL_DOCS\s*=\s*)NO/$$1YES/;' options.dox $(MAKE) html %.tag: %.dox diff --git a/deal.II/doc/doxygen/headers/base/instantiations.h b/deal.II/doc/doxygen/headers/base/instantiations.h new file mode 100644 index 0000000000..c6f46031ef --- /dev/null +++ b/deal.II/doc/doxygen/headers/base/instantiations.h @@ -0,0 +1,105 @@ +/** + * @page Instantiations Template instantiations + * + * The instantiation of complex function templates costs a lot of + * compile time and blows up the size of the resulting object + * files. Therefore, declaration and implementation of these functions + * should be split and the implementation should be read by the + * compiler only when really necessary. We achieve compile time + * efficiency by implementing the following concept: + * + * Template classes in deal.II are split into three + * categories, depending on the number of probable different + * instantiations. Accordingly, the function definitions are in + * different places. + * + * @section Inst1 Few instantiations + * + * These are the classes having template parameters with very + * predictable values. The typical prototype is + * @code + * template class Function; + * @endcode + * + * Here, we have a small number of instantiations (dim = 1,2,3) + * known at the time of design of the library. Therefore, member + * functions of this class are defined in a .cc file in the + * source directory and all instantiations are in the source file. + * + * This means that it is in fact not the template being part of the + * library, but its instantiation; in the case of triangulation + * objects of the deal.II library, implementations may be + * completely different indeed. There, we even put instantiations for + * different template parameters into different libraries. + * + * For these classes, adding instantiations for new parameters + * involves changing the library. + * + * @subsection Inst1a Available instances + * + * If the template parameter is dim, the available instances + * are for dim=1,2,3, if there is no other information. + * + * For other classes, the list of available instances is often listed + * in the line + @verbatim + Template Instantiations: few ( ) + @endverbatim + * + * @section Inst2 Some instantiations + * + * These are class templates usually having a small number of + * instantiations, but additional instantiations may be + * necessary. Therefore, a set of instantiations for standard + * parameters is provided precompiled in the libraries. + * + * Generic example of such a class is + * @code + * template class Polynomials::Polynomial; + * @endcode + * + * Here, the instantiations provided are for number types + * float, double and long double. Still, + * there are more number types and somebody might want to use complex + * polynomials. Therefore, complementing the declaration of + * Polynomials::Polynomial in polynomial.h, there is a file + * polynomial.templates.h, providing the implementation + * source code. + * + * @subsection Inst2c Creating new instances + * + * Choose one of your source files to provide the required + * instantiations. Say that you want the class template XXXX, + * defined in the header file xxxx.h, instantiated with the + * template parameter Lager. Then, your file should contain + * the lines + * @code + * // Include class template declaration + * #include + * // Include member definitions + * #include + * + * ... + * + * template class XXXX; + * @endcode + * + * @subsection Inst2p Provided instances + * + * Like with the classes in section Inst1, the instances provided in + * the library are often listed in the line pointing to this page, + * that is for example: + @verbatim + Template Instantiations: some ( ) + @endverbatim + * + * @section Inst3 Many instantiations + * + * These are the classes, where no reasonable predetermined set of + * instances exists. Therefore, all member definitions are included + * into the header file and are instantiated wherever needed. + * For an example, see + * @code + * template class SmartPointer; + * @endcode + */ -- 2.39.5