Both:
- Describe the API design and usage in the header: that’s your public interface for clients.
- Describe the implementation alternatives / issues and decisions in the implementation: that’s for yourself – later – and other maintainers/enhancers, even someone reviewing the design as input to some next-gen system years hence.
Comment anything that’s not obvious, and nothing that is (unless your documentation tool’s too stupid to produce good documentation without).
Avoid putting implementation docs in the headers, as changing the header means makefile timestamp tests will trigger an unnecessary recompilation for client apps that include your header (at least in an enterprise or commercial library environment). For the same reason, aim to keep the header documentation stable and usable – good enough that you don’t need to keep updating it as clients complain or ask for examples.