From 9230dd6a892e8d42013292c215d699a0dfde0171 Mon Sep 17 00:00:00 2001
From: Jakob Lykke Andersen <jakob@caput.dk>
Date: Wed, 6 Aug 2014 18:54:00 +0200
Subject: [PATCH] Doc, update C++ domain.

---
 doc/domains.rst | 78 +++++++++++++++++++++++--------------------------
 1 file changed, 36 insertions(+), 42 deletions(-)

diff --git a/doc/domains.rst b/doc/domains.rst
index 9b8b38612..4bfc91ec2 100644
--- a/doc/domains.rst
+++ b/doc/domains.rst
@@ -520,21 +520,24 @@ The C++ Domain
 
 The C++ domain (name **cpp**) supports documenting C++ projects.
 
-The following directives are available:
+The following directives are available. All declarations can start with a visibility statement
+(``public``, ``private`` or ``protected``).
 
-.. rst:directive:: .. cpp:class:: signatures
-               .. cpp:function:: signatures
-               .. cpp:member:: signatures
-               .. cpp:type:: signatures
+.. rst:directive:: .. cpp:class:: class speicifer
 
-   Describe a C++ object.  Full signature specification is supported -- give the
-   signature as you would in the declaration.  Here some examples::
+   Describe a class/struct, possibly with specification of inheritance, e.g.,::
+   
+      .. cpp:class:: SomeName::SomeClass : public MyBase, MyOtherBase
+
+.. rst:directive:: .. cpp:function:: (member-)function prototype
+
+   Describe a function or member function, e.g.,::
 
       .. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)
 
          Describes a method with parameters and types.
 
-      .. cpp:function:: bool namespaced::theclass::method(arg1, arg2)
+      .. cpp:function:: bool namespaced::theclass::method(T1, T2)
 
          Describes a method with unnamed parameters.
 
@@ -550,45 +553,24 @@ The following directives are available:
 
          Describe a constexpr function here.
 
-      .. cpp:member:: std::string theclass::name
+      .. cpp:function:: MyClass::MyClass(const MyClass&) = default
 
-      .. cpp:member:: std::string theclass::name[N][M]
+         Describe a copy constructor with default implementation.
 
-      .. cpp::type:: std::vector<int> MyList
+.. rst:directive:: .. cpp:member:: variable or member declaration
 
-         A typedef-like declaration of a type.
-
-      .. cpp:type:: theclass::const_iterator
-
-         Declaration of a type alias with unspecified type.
-
-   Will be rendered like this:
-
-      .. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)
-
-         Describes a method with parameters and types.
-
-      .. cpp:function:: bool namespaced::theclass::method(arg1, arg2)
-
-         Describes a method with unnamed parameters.
-
-      .. cpp:function:: const T &array<T>::operator[]() const
-
-         Describes the constant indexing operator of a templated array.
-
-      .. cpp:function:: operator bool() const
-
-         Describe a casting operator here.
-
-      .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
-
-         Describe a constexpr function here.
+   Describe a varible or member variable, e.g.,::
 
       .. cpp:member:: std::string theclass::name
 
       .. cpp:member:: std::string theclass::name[N][M]
 
-      .. cpp::type:: std::vector<int> MyList
+.. rst:directive:: .. cpp:type:: typedef-like declaration
+                   .. cpp:type:: name
+
+   Describe a type as in a typedef declaration, or the name of a type with unspecified type, e.g.,::
+
+      .. cpp:type:: std::vector<int> MyList
 
          A typedef-like declaration of a type.
 
@@ -599,8 +581,14 @@ The following directives are available:
 .. rst:directive:: .. cpp:namespace:: namespace
 
    Select the current namespace for the following objects. Note that the namespace
-   does not need to correspond to C++ namespaces, but can end in names of classes.
-   (e.g., ``Namespace1::Namespace2::SomeClass::AnInnerClass``)
+   does not need to correspond to C++ namespaces, but can end in names of classes, e.g.,::
+
+      .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
+
+   All following objects will be defined as if their name were declared with the namespace
+   prepended. The following cross-references will be search for by both their specified name
+   and with the namespace prepended.
+
 
 .. _cpp-roles:
 
@@ -611,7 +599,7 @@ These roles link to the given object types:
           cpp:member
           cpp:type
 
-   Reference a C++ object.  You can give the full signature (and need to, for
+   Reference a C++ object.  You can give the full specification (and need to, for
    overloaded functions.)
 
    .. note::
@@ -632,6 +620,12 @@ These roles link to the given object types:
    specific overload.  Currently Sphinx will link to the first overloaded
    version of the method / function.
 
+.. admonition:: Note on Template Delcarations
+
+   The C++ domain currently does not support template classes/functions/aliases/variables
+   (e.g., ``template<typename T> MyClass``), only template instantiations
+   (e.g., ``MyClass<T>``).
+
 
 The Standard Domain
 -------------------