Documentation in the Era of Concepts and Ranges

By Christopher Di Bella and Sy Brand

Concepts and ranges change how we should think about documentation in C++. Concepts give us a new way to explicitly constrain templates without resorting to arcane tricks, directly stating requirements on our interfaces as code. Ranges allow us to restructure our programs to describe what the code should do by composing named patterns rather than how it should do it through state-manipulating operations. As a facility for specifying requirements, to what extent are concepts self-documenting for users of a given interface? How should we balance pure-code descriptions of our interfaces with textual descriptions? How can we use them in aid of creating documentation tuned for our target audience and give them the information they need in a digestible format? We’ll discuss these questions, propose some answers, look at existing documentation from real-world projects, and use ranges as a case study for documenting concepts-based APIs.