Dismiss
InnovationQ will be updated on Sunday, Oct. 22, from 10am ET - noon. You may experience brief service interruptions during that time.
Browse Prior Art Database

Automatically Generating Formatted Documentation for Object-Oriented Class Libraries

IP.com Disclosure Number: IPCOM000114399D
Original Publication Date: 1994-Dec-01
Included in the Prior Art Database: 2005-Mar-28
Document File: 4 page(s) / 200K

Publishing Venue

IBM

Related People

Acker, LE: AUTHOR [+2]

Abstract

Disclosed is a technique for maintaining formatted documentation for constantly changing object-oriented class libraries. The technique uses a mechanism for automatically generating and regenerating the preformatted documentation from class interface specifications written in Interface Definition Language (IDL).

This text was extracted from an ASCII text file.
This is the abbreviated version, containing approximately 28% of the total text.

Automatically Generating Formatted Documentation for Object-Oriented
Class Libraries

      Disclosed is a technique for maintaining formatted
documentation for constantly changing object-oriented class
libraries.  The technique uses a mechanism for automatically
generating
and regenerating the preformatted documentation from class interface
specifications written in Interface Definition Language (IDL).

      The importance and popularity of Object-Oriented Programming
Systems (OOPS) has produced a variety of programming languages and
systems, such as SOM and C++.  Using these systems, highly complex
class libraries can be developed.  To use these libraries
effectively, these classes and their relationships within a class
hierarchy must be accurately documented with the most current
information.  The difficulty of maintaining complete and correct
documentation is more severe with object-oriented class libraries
than with traditional software systems.  Object-oriented systems
permit users to customize (override) much of the system, which
exposes far more of its internal functions (called "methods") than in
traditional systems.  In addition, these methods are ordered within
highly complex class hierarchies.  This ordering means that it is no
longer sufficient to document just the "leaf" functions as the API to
a system.  Many of the internal functions must be documented as well.

      To ensure the correct and consistent overriding of the methods
in an object-oriented system by users, and to promote the
understanding of the complex hierarchical relationships, the
documentation must be correct and complete, and the documentation
must be constantly revised to reflect changes in the class library.
Manual methods to achieve this, however, are error-prone and
time-consuming.  The solution is a program for automatically
generating documentation files directly from IDL class interface
descriptions.  These documentation files are pre-formatted, to avoid
the cost of reformatting ASCII documentation files each time class
interfaces are revised.  In this implementation, the files are
formatted in Interleaf, but the technique can apply to any text
formatting system that can store formatting commands as ASCII text.

      The technique presented automatically generates documentation
files from the class interface specifications given in IDL.  IDL is
the Common Object Request Broken Architecture (CORBA) standard
language for describing class interfaces.  The System Object Model
(SOM) Compiler is an IDL compiler that analyzes IDL class interface
descriptions and generates various output forms, using various
back-end emitters.  The program for generating formatted
documentation files is implemented as an emitter for the SOM
Compiler.  The emitter is written using SOM's Emitter Framework, a
class library designed to facilitate the implementation of new SOM
Compiler emitters.  The Emitter Framework is template-based, so that
the...