| Edit | Rename | Changes | History | Upload | Download | Back to Top |
Summary
SmalltalkDoc is a web application that generates API documentation for VisualWorks. It provides reference documentation for the package and class library. SmalltalkDoc presents a "snapshot" of one version of the system, reading it from a Store repository. XHTML-formatted summaries are provided for bundles, packages, classes, name spaces, and shared variables.
This document explores the functional requirements for SmalltalkDoc, and some details of its implementation.
Objectives
SmalltalkDoc is intended for both new and experienced VisualWorks developers. It may also be helpful for developers who are evaluating VisualWorks for future projects, as it enables them to examine the class library without actually downloading or installing the product. By identifying public interfaces, SmalltalkDoc separates the most important parts of the package and class library from all of the implementation-level classes and methods that are largely irrelevant (and disorienting) for new users.
To build a catalog of reference documentation, SmalltalkDoc communicates with a Store repository to create a "snapshot" of one version of the VisualWorks system. SmalltalkDoc provides a means to automatically generate summaries for bundles, packages, classes, and name spaces. API-style documentation is generated for individual classes. All summaries are housed in a content management framework on the application server, so SmalltalkDoc can be faster and more flexible than our current Store repositories.
SmalltalkDoc is being created to document VisualWorks components, but also includes support for third-party or end-user components. Third parties may either submit their (documented) components for inclusion as third-party add-ons in the SmalltalkDoc "overview", or they could eventually create their own instance of SmalltalkDoc, maintaining it as they like. For example, by adding appropriate properties to the PostgresSQL EXDI package, it could easily be added to the "Database" category in the SmalltalkDoc overview for VisualWorks.
Guidelines for content authoring will be provided in a subsequent document.
Functionality
From a user’s perspective, SmalltalkDoc provides the following basic functionality:
Overview
The class library overview is organized into "functional areas" or "frameworks", where each area may contain some number of bundles or packages. Selecting a functional area shows all the bundles or packages contained with it. Selecting one of the bundles or packages displays a summary of its contents.The overview is presented as a hierarchical view that is one level deep. A deeper hierarchy would give us more flexibility for organization, but it would only make things correspondingly more difficult to find (which is one of the problems that SmalltalkDoc is intended to ameliorate).
From the overview, one can inspect components, as well as the classes, name spaces, and interfaces within them.
In 2006, Cincom has decided to begin work to reify "projects" as first-class meta objects that can be published in a Store repository. SmalltalkDoc will use projects to express a class library overview.
Bundle View
The bundle view shows a list of all bundles in the repository. Selecting a bundle in the list displays a detailed summary of its contents. The bundle view, like the overview, is structured like a Smalltalk inspector. I.e., it is possible to "dive" through the structure by clicking on the packages contained in the selected bundle, revealing their constituent classes, name spaces, and interfaces. To keep the display simple (and to follow the model of the Smalltalk inspector), this view shows the bundles in a simple list, not a hierarchical display.Package View
The package view is structurally similar to the bundle view. It shows a list of all packages in the repository. Selecting a package in the list displays a detailed summary of its contents. The package view, like the bundle view, is structured like a Smalltalk inspector. I.e., it is possible to "dive" through the structure by clicking on the classes and name spaces contained in the selected package.Glossary
The glossary shows a list of Smalltalk-specific terms, which are linked to the bundle, package, class, and name space comments. For users who are unfamiliar with Smalltalk terminology, the glossary provides convenient definitions.Search
SmalltalkDoc includes a built-in search engine that allows basic or advanced searches. A basic search (which accepts wildcards) returns the results of a full-text search against all names of bundles, packages, classes, and name spaces, as well as against the comments associated with them. The advanced search allows users to more precisely query by the name of the component, by its type (e.g., bundle, package, class, or name space), by its publisher (author), by words in the description, or by summary keywords (e.g., "network" or "XML").
Behind the scenes, SmalltalkDoc also includes functionality for summarizing the contents of a Store repository, and additional functionality for content management. This functionality is only intended for administrators or developers who maintain SmalltalkDoc. Much of the administrative functionality is provided by Shoji, the content management framework used to implement SmalltalkDoc (for details, see Implementation, below).
SmalltalkDoc does not attempt to be a full repository browser. Rather, it includes a mechanism for summarizing the contents of a repository into documents that are stored in a local database (in fact, a Shoji instance). In effect, using a web browser to explore SmalltalkDoc involves browsing local documents stored in a Shoji CMF.
Use Cases
There are three general use cases for SmalltalkDoc:
The second use case for SmalltalkDoc involves preparing code for summarization. This is achieved by editing properties associated with bundles, packages, classes, and name spaces. These properties have been roughly derived from the earlier Documentation Standards Proposal, though many of them are optional. For details on these requirements, see Content, below.
The third use case for SmalltalkDoc involves generating content. This is distinct from the work involved in authoring the content for components, classes, and methods. "Generating" content is the process of summarizing a particular version of VisualWorks that is stored in a Store repository. This is handled through a special administrator’s web interface to the SmalltalkDoc application. The administrator specifies a version of VisualWorks to be summarized, a target repository, a local database, and then launches the summarizer. Due to the speed of the code repository, anywhere from 4 to 6 hours may be required to completely summarize a single version of VisualWorks.
Content
All functionality and content is presented via a simple web interface, with a tab control to select between the overview, the bundle and package views, the glossary and search pages. The overview and component (bundle and package) views, provide a means to browse reference documentation and summaries.
The following tables describe the summaries in greater detail, indicating the elements that are required, and those which are optional. Some of these elements already exist, some do not (see the Content Requirements section, below, for details).
Bundle Summary
[TBD]
Package Summary
[TBD]
Class Summary
[TBD]
Name space Summary
[TBD]
Content Requirements
As mentioned in the previous section, SmalltalkDoc automatically generates summaries by reading definitions from a Store repository. Some of the summary content is generated using pre-existing information (e.g., version strings). However, many of the most useful properties do not yet exist, and must be added. SmalltalkDoc establishes a framework for standardizing this information.
The task of adding the missing information involves both writing the content and some modifications to the base VisualWorks system. The latter are required because VisualWorks does not currently provide a way to associate reference documentation with classes and name spaces.
In the case of code components (bundles and packages), properties containing reference documentation may be adding using the existing framework. SmalltalkDoc provides the templates and guidelines for creating this content. VisualWorks components already provide support for properties, and it should not be difficult to build minimal tools to help edit and maintain these properties. In fact, the System Browser already allows one to edit these properties, but the UI is awkward and not really suitable for writing content.
In the case of properties associated with classes and name spaces, additional framework must be added to the VisualWorks base image. Currently, classes and name spaces only support a "comment string". This is inadequate for SmalltalkDoc, and so our recommendation is that the comment string be replaced or supplanted with a XML or XHTML-formatted list of properties. These would be loaded and stored using the existing mechanisms for source files, though some modifications to the VisualWorks tools would be required to support the new properties.
In early 2004, we are finalizing the XML schema for representing this information. Specifically, in place of a plain text string for class comments, the system would henceforth store something like this:
<Summary>A Bag is an unordered collection of elements.</Summary>
<Description>A Bag is like a Set that permits duplicates. While it does not waste space by keeping the actual duplicates, it does keep a count of the occurrences of each object. Since, like a Set, a Bag's elements are not kept in any order, knowing how many times a given object occurs is equivalent to having that many copies of it in the Bag<br/>Because a Bag does not actually store duplicates, it is more space-efficient than an Array or List. An Array or List preserves the order of its elements, however. The difference shows up when you loop through (enumerate) the elements -- the same Bag may loop through its elements in a different order each time, while an Array or List offers a predictable order.<br/>When using a Bag, it is important to remember the distinction between #== and #=. When an object is added to a Bag, it is tallied and discarded if it is #= to an existing element. Thus, the application cannot expect to use #== after retrieving that element, since it may get an equal but not identical object.</Description>
<Keywords>Collections; Collections-Unordered</Keywords>
The completeness of this reference material may be verified by a series of tests. During the Spring of 2003, the VisualWorks group agreed that the existing code review process should be augmented to require that all new or altered code pass a minimal set of documentation tests. These tests should be expressed in a revised and supported tool (e.g., AT System Analysis, Browser Code Tool, or Code Critic).
The documentation tests should verify the following minimal requirements:
As noted earlier, SmalltalkDoc provides a way to summarize the contents of a Store repository, and save the summaries as documents in a Shoji instance. Shoji provides support for simple document management and annotations, user profiles, groups, and a mechanism for registering users. Registered users may annotate the documents containing the SmalltalkDoc summaries. While SmalltalkDoc is not intended to be used as a document authoring system, it does provide a way (using Shoji) to annotate documents. Annotations are useful as a feedback mechanism, so that VisualWorks developers have a way to communicate directly while they are browsing SmalltalkDoc.
When installing SmalltalkDoc on a server, a Shoji instance must be initialized first. This is accomplished using a administrator's web interface to Shoji. Next, the SmalltalkDoc web application must be prepared for use. This involves generating summaries for a specified version of all components in the repository, and then storing them as documents in the Shoji CMF. SmalltalkDoc uses StoreForGlorp to fetch all the components and definitions from the repository. Shoji handles the general document management, and provides support for indexing and 'sections', which are specialized views on the document database. A client session involves pulling preprocessed documents out of the Shoji database, and so queries are fast.
For the objects in the repository, SmalltalkDoc generates an index (a 'section' in the parlance of the CMF) for the following: Overview; Bundles; Packages; Classes; Name spaces; Class APIs; Authors. Each section is a collection of documents stored in the Shoji CMF, where each document is a summary of the object that can be displayed in a Web browser.
Finally, SmalltalkDoc also provides a new "Documentation" code tool in the VisualWorks system browser. This is used for writing the SmalltalkDoc comments. The code tool currently uses the Twoflower HTML display widget to present the SmalltalkDoc content in a structured fashion. In the future, we want to replace the Twoflower widget with the WithStyle XML display subsystem.
Status
Much of what is described on this page has been implemented. A prototype version of SmalltalkDoc was assembled early in 2003, and the VisualWorks group encouraged its further development. During the Fall 2003 planning meeting in Santa Clara, the group began discussions about adding base image support for SmalltalkDoc. Work has continued through 2004. In 2005, the first version of SmalltalkDoc was delivered in the /preview directory of VisualWorks 7.3.
Project development is active, with a targetted delivery date late in 2006.
Created: Nov. 12, 2003, M. Downing Roberts — First draft.
| Edit | Rename | Changes | History | Upload | Download | Back to Top |