title: Where to document interfaces in C++?
body: <p>I have more of a Java background, thus let me illustrate with a Java example. Say the following code exists:</p>
  
  <pre><code>interface iFoo {
      /* Do foo */
      void foo();
      /* Do bar */
      void bar();
  }
  
  class A implements iFoo {
      void foo() {};
      void bar() {};
  }
  
  class B&lt;iFoo&gt; {
      iFoo foo;
      B() {
          foo.foo();
          foo.bar(); 
      } 
  } 
  
  //somewhere in the code:
  B b = new B&lt;A&gt;();
  </code></pre>
  
  <p>Now if I want to implement a class C that can be used as the type parameter for B, I know that C has to implement iFoo. Thus, I go there and by design-by-contract convention, all the necessary documentation will be there (which methods do I need to implement, what is there signature plus inline documentation.</p>
  
  <p>In C++, it would look like this (correct me if I am wrong):</p>
  
  <pre><code>class A {
  public:
       void foo();
       void bar();
  }
  
  template&lt;class T&gt;
  class B {
  public:
      T foo;
      B() {
          foo.foo();
          foo.bar(); 
      } 
  } 
  
  //somewhere in the code:
  B *b = new B&lt;A&gt;();
  </code></pre>
  
  <p>Where is the best place to document what B expects of T? Or the other way around, if I have A and B and want to implement a class C that is passed as type parameter to B, how do I find out what B expects of T? The above is of course a very trivial example, just imagine bigger and more complex classes. </p>