A Framework for Framework Documentation

Abstract

Frameworks are quite difficult to understand when one first 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 flexibility 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 different aims and audiences in mind. In this paper, we present a task-oriented framework for framework documentation. Our framework is based on first identifying a set of framework (re-)use cases, which we then decompose into a set of elementary engineering tasks. Each such task requires a set of documentation primitives, enabling us to specify a minimal set of documentation primitives for each framework usage scenario. We study some major framework documentation approaches in light of this framework, identifying possible deficiences and highlighting directions for further research. Categories and Subject Descriptors: D.2.m [Software]: Miscellaneous-Reusable Software; D.1.5 [Programming Techniques]: Object-oriented Programming. © 2000, ACM. All rights reserved.