A framework for framework documentation

Abstract

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 andIslam 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 fra...

Learning from examples to improve code completion systems

“…A large number of framework documentation techniques exists [7]. Prescriptive techniques such as cookbooks, tutorials, exemplars, and pattern languages document how to customize a framework in order to accomplish a specific task [11,15].…”

Patterns and Tools for Improving Framework Understanding: A Collaborative Approach

“…To be complete, the overall documentation of a framework usually combines a lot of information that must be produced, organised, and maintained consistent. The documentation must describe the application domain covered by the framework, its purpose, how-to-use it, how it works, and to provide details about its internal design, which globally may involve a large diversity of contents, and many different ways of presenting them [BKM00].…”

Identifying and addressing problems in object-oriented framework reuse

“…Butler et al have proposed a 'framework' for framework documentation (Butler et al 2000). This is derived from a theoretical analysis of a range of potential framework uses from simple instantiation through to, "... mining a framework for design ideas to use in other frameworks".…”

“…Whilst practical evidence does suggest that framework usage can increase reusability and decrease development effort (Moser and Nierstrasz 1996), experience has identified a number of issues that complicate framework application and limit potential benefits (Bosch et al 1999). One of the major challenges is effective framework understanding (Butler et al 2000). This paper presents the details of a long-term empirical investigation into two related aspects of framework understandingidentification of the key problems that arise during framework reuse and evaluation of documentation that aims to address these key problems.…”