A framework for framework documentation

Frameworks are quite di cult to understand when one rst uses them: the design is very abstract, to factor out commonality the design is incomplete, requiring additional subclasses to create an application the design provides exibility for several hotspots, not all of which are needed in the application at hand and the collaborations and the resulting dependencies between classes can be indirect and obscure. Many approaches to documenting frameworks have been tried, though with di erent aims and audiences in mind. In this paper, we present a task-oriented framework for framework documentation. Our framework is based on rst identifying a set of framework (re-)use cases, which w e then decompose into a set of elementary engineering tasks. Each s u c h t a s k requires a set of documentation primitives, enabling us to specify a minimal set of documentation primitives for each f r a m e w ork usage scenario. We study some major framework documentation approaches in light of this framework, identifying possible de ciences and highlighting directions for further research.