I'm re-working some prototype code into a policy based design in C++, and I'm wondering what the best practice is for documenting the design. My current plan is to document:

• Policy hierarchy
• Overview of each policy
• Description of each type/value/function in each policy

I was thinking of putting this into a doxygen module, but this looks like it will be a bit awkward since formatting will have to be done by hand without code to base the doc on (that is, documenting the policies rather than the implementation of the policies).

So my questions are:

• Are there other aspects of the design that should be documented?
• Are there any tricks to doing this efficiently in doxygen?
• Is there a tool other than doxygen thats better suited to this?
• What are some examples of well documented policy based design?

This is my first serious attempt at policy based design. I think I have a working grasp of the principles, but whatever naivety I expose in this question is fair game for an answer too.