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. Permission to make digital/hard copy of part or all of this work for personal or classroom use is granted without fee provided that copies are not made or distributed for pro t or commercial advantage, the copyright notice, the title of the publication, and its date appear, and notice is given that copying is by permission of the ACM, Inc. To copy otherwise, to republish, to post on servers, or to redistribute to lists, requires prior speci c permission and/or a fee. Copyright 2000 ACM 00360-0300/00/0300es 2 G. Butler, R.K. Keller and H. Mili 1. INTRODUCTION Frameworks are introducted to support the development of families of applications through reuse Fayad and Schmidt 1997 Mili et al. 1995]. The design of a framework de nes and xes certain roles and responsibilities amongst the classes, as well as standard protocols for their collaboration. The variability within the family of applications at hand is factored into so-called \hotspots" Pree 1995] , and the framework provides simple mechanisms to customize each hotspot. A framework is not an easy thing to understand when one rst uses it: the design is very abstract, to factor out commonality the design is incomplete, requiring additional subclasses to create an application the design provides (too much) exibility, not all of which may be 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 D enomm ee 1999 Campbell and Islam 1993] , though with di erent aims and audiences in mind. These different audiences | application developer, framework maintainer, and framework developer | have quite di ering needs from documentation. In this paper, we propose a framework for specifying the documentation needed for each kind of framework usage, and we study existing approaches for the extent to which they address those needs. Our approach is based on an analysis of the various framework (re-)use cases, ranging from simple instantiation to the case of mining a framework for design ideas to use in other frameworks. For each s u c h (re-)use case, we identify a set of elementary (software) engineering tasks, each w i t h its own documentation needs such needs are expressed in terms of documentation primitives. This setting is shown in Figure 1 using OMT notation.
A large number of framework documentation techniques exists REF .
A framework for framework documentation
CSUR
Computer Science