Browse Prior Art Database

Directives for Controlling Automatic Document Generator for System Object Model Interface Definition Language

IP.com Disclosure Number: IPCOM000116380D
Original Publication Date: 1995-Sep-01
Included in the Prior Art Database: 2005-Mar-30
Document File: 2 page(s) / 101K

Publishing Venue

IBM

Related People

Chow, A: AUTHOR [+2]

Abstract

Disclosed is a technique for controlling an automatic document generator for IBM* System Object Model Interface Definition Language (SOM* IDL) files. The generator is assumed to be written using the SOM Emitter Framework. In particular, the technique solves the problem that the SOM IDL compiler can identify, and associate comments with, only a fixed set of SOM IDL entities, whereas document specification typically requires specifying a larger set of textual entities.

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

Directives for Controlling Automatic Document Generator for System
Object Model Interface Definition Language

      Disclosed is a technique for controlling an automatic document
generator for IBM* System Object Model Interface Definition Language
(SOM* IDL) files.  The generator is assumed to be written using the
SOM Emitter Framework.  In particular, the technique solves the
problem that the SOM IDL compiler can identify, and associate
comments
with, only a fixed set of SOM IDL entities, whereas document
specification typically requires specifying a larger set of textual
entities.

      The technique involves placing one or more instances of a
general-purpose directive in the IDL comments, and arranging for the
generator (also known as an emitter) to recognize and process these
directives.  The directive essentially allows emitter symbols to be
defined in IDL comments and bound to arbitrary text.  These symbols
can then be used in the emitter output template.  Wherever the
symbols occur in the template, the associated text is substituted at
output generation time.

      While this technique was motivated by, and developed in the
context of, documentation emitters, it is applicable to other kinds
of emitters.

      The problem solved by the technique is described in more detail
as follows.

      Automatic generation of documentation from SOM IDL files relies
on the ability of the SOM IDL compiler to associate IDL comments with
specific SOM IDL entities, such as classes, constants, types,
constructed type members, exceptions, exception members, attributes,
methods, method parameters, overridden methods, and so on.

      The ability of the SOM IDL compiler to make this association is
essential, but unfortunately, not sufficient, in general, for
specifying the documentation.  The limitation is that the compiler
knows only about a fixed set of logical entities (in particular,
those defined by SOM IDL, for example, interfaces, attributes,
methods, and so on) and can present only these entities and their
associated comments to the document emitter.

      There can exist other entities about which the compiler has no
knowledge, but which are important to the document generator.  Most
likely, this situation arises because the entities are defined at a
conceptual level above SOM IDL and need to be documented.  Currently,
there is no defined place in the SOM IDL file in which to place the
documentation text associated with these non-IDL entities.

      For example, consider a user interface toolkit.  In the
toolkit's programming model, visual objects can receive events.  The
set of events that a particular visual object can receive is
something that should be...