The pattern applier requires pattern documentation to select an applicable pattern, to apply the pattern, and to project the results of the pattern application. Different types of documentation is generated or contributed by the pattern author to match the needs of the pattern applier.
Except for the overview diagram, all documentation is included in two types of standard RAS asset manifest files that support either the pattern library or the pattern structures. Manifest files contain the static data for the pattern and are identified by their file extension of .rmd, for Rational® Manifest Documentation file extensions. Some manifest data is shared with pattern properties such as the Short Description property. Portions of the stored data are presented to the pattern applier when relevant to the pattern task.
To assist searching repositories for patterns, the pattern author can include multiple keywords in the pattern design. To assess search matches, the pattern applier reviews the pattern manifest files in the RAS Asset Explorer view to choose a pattern to import. In the Pattern Explorer view, an HTML page with a short description reminds the pattern applier of the type or purpose of each pattern and parameter. An Overview page discloses the relationships between the major pattern components. Pattern online help reveals static data such as the UML 2.0 types of the parameters and in which groups the library's patterns are organized. Depending on the pattern complexity, the pattern author may have included a simple or extensive description of the pattern in the online help. In the diagram editor, the pattern applier can use the parameter tooltips in the pattern instance when specifying arguments for the pattern or open the overview compartment to review the overview diagram.
Providing Short Description text
Every pattern and parameter includes a Short Description property to briefly describe the use or purpose of the pattern or parameter. You can provide a short description when adding the new patterns and parameters to the pattern library. Short descriptions can also be added or modified in the Properties view.Adding overview diagrams
The pattern author can add an image file to each pattern that visually models the major pattern components and relationships between them. The file must be a Graphics Interchange Format (GIF) file and it must be located in the pattern project.Generating documentation files
You can generate sets of project files that include standard information about the pattern library and its contents. The generated files are opened by the pattern applier from the Pattern Explorer view and they are displayed as part of the online help topic hierarchy.Importing documentation
Extensive documentation may be required for complex patterns or for an audience of new pattern users. Documentation can be imported into the static pattern data. This documentation is available to the pattern applier in the online help system listed under the heading Description.Adding documentation to pattern libraries
The pattern library maintains information about its member patterns in a static data file. You can add documentation to this library manifest file for the pattern applier to use.
Parent topic: Modifying patterns during design
Related concepts
IBM Rational design patterns
Pattern code and support files
RAS pattern assets
Pattern project contents