From 41e0e56091413426ace0cab73266806a0b43b287 Mon Sep 17 00:00:00 2001
From: Denis Davydov <davydden@gmail.com>
Date: Thu, 27 Oct 2016 17:10:22 +0200
Subject: [PATCH] document coding conventions for templates

---
 doc/doxygen/headers/coding_conventions.h | 41 ++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/doc/doxygen/headers/coding_conventions.h b/doc/doxygen/headers/coding_conventions.h
index 02ab55bf35..6d3bf13bf7 100644
--- a/doc/doxygen/headers/coding_conventions.h
+++ b/doc/doxygen/headers/coding_conventions.h
@@ -161,6 +161,47 @@ source files.
 </ol>
 
 
+<h3>Instantiation of templated functions/classes</h3>
+
+<p> Majority of classes and functions in deal.II are templated. This brings a
+question of how and where such objects are instantiated, if at all. Throughout
+deal.II we adopt the following convention:</p>
+
+<ol>
+
+<li> If we can enumerate all possible template arguments (e.g., the dimension
+can only be 1, 2, or 3), then a function template goes into the <code>.cc</code> file and
+we explicitly instantiate all possibilities. Users will not have any need to
+ever see these function templates because they will not want to instantiate
+these functions for any other template arguments anyway. </li>
+
+<li> If we can not enumerate all possible template arguments (e.g., vector
+types -- because users might want to define their own vector kinds) but at
+least know a few common usage cases, then the function is put into a
+<code>.templates.h</code> file. We #include it into the <code>.cc</code> file and instantiate the
+functions for all of the common arguments. For almost all users, this will be
+just fine -- they only use the (vector, matrix, ...) types we already
+instantiate, and for them the <code>.templates.h</code> file will not be of any interest.
+It will also not slow down their compilations because nothing they see will
+#include the <code>.templates.h</code> file. But users who define their own
+(vector, matrix, ...) types can instantiate the template functions with their
+own user-defined types by #includeing the <code>.templates.h</code> files.
+
+<li> Finally, if we can not assume in advance which values template arguments
+will take (e.g., any class derived from Subscriptor can be used as an argument),
+the definitions of functions are provided at the bottom of the header
+file with declarations. The definitions should be guarded with <code>#ifndef DOXYGEN ...
+#endif</code> to prevent Doxygen from picking them up.</li>
+
+</ol>
+
+<p> For the first two cases, instantiation instructions are defined in .inst.in
+files. These files are processed by custom CMake scripts to generate <code>.inst</code> files
+using lists of parameters (vector classes, dimensions, tensor ranks, etc)
+defined in <code>cmake/config/template-arguments.in</code>. It is those <code>.inst</code>
+files that are eventually included from the corresponding <code>.cc</code> files. </p>
+
+
 <h3>Defensive programming</h3>
 
 <p> Defensive programming is a term that we use frequently when we talk about
-- 
2.39.5