Doxygen Templates – Does Doxygen Support Templates for HTML Output?

Updated (2016/08/24)

Recommended article with focus on C++11:

An introduction to C++'s SFINAE concept: compile-time introspection of a class member (Jean Guegant)

As a learner of C++ Template Metaprogramming a few months ago, I would still recommend to read this book.

It does not include C++11, but it lays out the syntax and the C++ specifications on how a compiler should process template code. The book covers a lot of less known corners which will become crucial if you need to use C++ templates substantially, whether or not metaprogramming is involved.

The missing parts from C++11 are:

• Type Trait Support.
  • http://en.cppreference.com/w/cpp/types
  • For navigation, mouse over the "Type Support" near the top of the page. A list of is_* will be displayed.
• decltype. http://en.cppreference.com/w/cpp/language/decltype
• declval. http://en.cppreference.com/w/cpp/utility/declval
• move http://en.cppreference.com/w/cpp/utility/move
• forward http://en.cppreference.com/w/cpp/utility/forward

There is a construct which you will see a lot in code that is pasted onto Stackoverflow: std::enable_if. However, in practice, I find this quite difficult to use, because of the One-Definition Rule and SFINAE. This is why this book is important, because it goes over the basics.

If you use C++ templates substantially in a cross-platform library, you will need to test-compile your code in different compilers. This is because each compiler has different level of compliance to the C++ specification. Code that compiles fine on one may be reject by the other, and occasionally the compiler that accepts it is the one that breaks the specification.

Here is my reading notes when I go through this book. Hope it will be helpful.

Book reading notes - C++ Templates - The Complete Guide (2003)

• Ch 2.5 - Function Templates - Summary
  • Overload resolution, and best practices
• Ch 3.3 - Specialization of Class Templates
• Ch 3.4 - Partial Specialization
  • Ambiguity (ODR error), and how to resolve it. ODR = One-Definition Rule
• Ch 4.3 - Restrictions for Non-type Template Parameters
  • Example: string literals with external linkage

• Ch 5 and Ch 6 - These two chapters are very depressing. You may want to skip it and then go back when you are emotionally ready for using templates.

• Part II (Ch 8 - Ch ???) The section of advanced stuff.

• Ch 8 - More rules

  • For a programmer already familiar with the entire Ch 3 (class templates - basics), Ch 8.1 and 8.2 should be read immediately following Ch 3, because the additional rules are just as important and relevant as the basic rules. This will save some pain.

• Ch 8.3.1 (Page 106 in 12th Printing) mentions SFINAE for the first time.

• Ch 8.3 - This section introduces a lot of circumstances where template argument substitution would have led to nonsensical syntactic expansions (and thus become invalid, which in return necessitates SFINAE). This chapter has a steep learning curve even for the experienced C++ programmers.

• Ch 11 - Template Argument Deduction

  • Ch11 contains some contrived Template Argument Deduction examples that are necessary for understanding some of the equally contrived SFINAE applications.

• Ch 12.4 onward - Partial class template specialization.

  • This covers the internal mechanics that is often called upon in an SFINAE application.

Part III (Ch 17 - Ch ???) Metaprogramming.

• Ch 17 - Begins with introductory functional programming.

• App. A.3 - One-Definition Rule (ODR) in detail.

Generated documentation's audience is developers who are trying to use the code. Meaning the code is a reusable library or framework.

If code is named and structured properly, documentation is not as important. I have found that the most important documentation is at the class or module (namespace, package, etc) level. The least important documentation is at the function or method level.

In order to make the documentation meaningful and useful to developers, be sure to describe the purpose of classes and how they are used together. If I have an e.g. PrintJob class, I know what it is. But how does it interact with a PrintManager or PrinterProperties? What is the process of taking an object and printing it? How do these objects work together? I would expect to see a short code example showing the class interactions.

Generated documentation must also include pre- and post-conditions in plain English at the function level where appropriate. If your print() function expects a job to be in a certain state, tell me. I do not want to dig around in the code to decipher what it needs. Once the printing is done, can I reuse the job to print a second copy or is it now invalid?

Finally, omit documentation for entities that truly are simple and do not need it. If you have a List, you do not need to document the size() function. I understand it will be a nonnegative integer, and based on the data type, I know how big it can be. This reduces fluff. When I am scanning documentation, I know that if I see text, it is important. It is not documenting something that is common-sense to a developer.