Documentation of resources

In addition to viewing resources, you might want to document the applications that you are building. WebSphere® Integration Developer provides a tool to generate documentation for the artifacts in your modules, mediation modules, and libraries.

Initiate the documentation generation by invoking a wizard. You can customize the contents of the documentation by selecting multiple resources from one or more modules and libraries so that all the information will be written to a single report, which is a PDF file. You can also specify the layout and fonts for the output. See "Generating documentation" in the related tasks for detailed instructions on how to create documentation.

Resource documentation

The documentation generator produces the following information for these resources:

Other resources will not be documented by the documentation generator.

Referenced files

The documentation generator can also produce documentation for the selected resources and the resources that they reference. For example, in the Documentation Generation wizard, you can select the business process and the Include referenced files option. As a result, the generated PDF report will also have information for the resources (such as interfaces invoked by its activities) that the process references.

Documentation structure

The generated PDF report has the following structure:

  • Title page

    Has the report title, author name, and report date.

  • Table of contents

    Lists the sections and page numbers in the report.

  • Resource documentation sections

    Lists the properties of the resources. Except for the module and library, all resources also have pictures of the resources opened in the Editor view.

  • Cross reference

    Lists for each documented resource, which resource uses it (Providers list), and where it is used (Receiver list).

  • Appendix: Documentation generation settings

    Lists the documentation generation settings that were specified in the Documentation Generation wizard and used for the PDF report.

Documentation layout and style

The layout and the style of the generated PDF report can be customized with the Documentation Generation Wizard. If you change the layout and style settings, they are saved for all subsequent documentation generations, until they are changed again.

The following layout settings can be modified:

  • Paper size

    Defines the paper size of the generated documentation.

    Default value: Letter

  • Table of contents level

    Defines the maximum level of topics to be listed in the table of contents of the report.

    Default value: 7

  • Font
    Defines the font family, font size, and font style for the output. The default font settings are:
    • Plain text

      • Used for the description and documentation of different artifacts. The font family of plain text is also used for the title page, the header, and the footer.
      • Default font family: Helvetica
      • Default font size: 10
      • Default font style: regular
    • Chapter title

      • Used for the numbered headings, the header of table of contents, and the header of the appendix
      • Default font family: Helvetica
      • Default font size: 14
      • Default font style: bold
    • Source code text

      • Used for the documentation of source code such as Java
      • Default font family: Courier
      • Default font size: 10
      • Default font style: regular
    • Caption text

      • Used for the captions of images
      • Default font family: Helvetica
      • Default font size: 10
      • Default font style: bold
    • Definition text

      • Used for the documentation of key-value pairs
      • Default font family: Helvetica
      • Default font size: 10
      • Default font style: regular
    • Header text

      • Used for the unnumbered headings
      • Default font family: Helvetica
      • Default font size: 11
      • Default font style: bold
    • Table of contents

      • Used for the table of contents
      • Default font family: Helvetica
      • Default font size: 9
      • Default font style: regular

Master files to save settings

A master file is a resource profile defining the contents (not the font styles) to be included in the generated documentation. When using the Documentation Generation wizard, create a master file to save your resource selections and the next time you use the wizard to update the same report, just select the existing master file.

Register new fonts

The documentation generator provides three default fonts that can be used in the documentation. These fonts are Helvetica, Courier, and Times with the font styles: regular, italic, bold, and bold italic.

You can add a new font, which is either a true type font file (.ttf) or true type collection file (.ttc) by registering it. Font registration is done from the Documentation Generation wizard. Once a font is registered, it can be used for all reports until it is removed. Default fonts cannot be removed. See "Generating documentation" under related tasks for instructions on how to work with the Documentation Generation wizard.

Note: In the Documentation Generation wizard, names of registered fonts, including double-byte character set font names, are displayed only in Latin letters.

Trace file

The documentation generator can write documentation generation trace messages into a trace file. Do not turn on this tracing function unless there is a problem with the documentation generator, because tracing impacts system performance and can take up a lot of disk space. The trace is set in the Preferences window and output is written into a text file in the metadata directory (workspace-name\.metadata\.plugins\com.ibm.wbit.reporting.infrastructure\trace\). Log entries are appended and never erased.

Related concepts
Modules and libraries
Modules and libraries dependencies
Business integration capabilities and roles
Business integration cheat sheets
Best practices: Sharing projects
Related tasks
Creating a module for business services
Creating a mediation module
Changing default namespaces
Enabling tools capabilities
Adding dependencies to modules and libraries
Creating the library
Generating documentation

Related information

Tutorial: Work with modules and libraries

Feedback
(C) Copyright IBM Corporation 2005, 2006. All Rights Reserved.