Editing a Documentation Template

Overview

Editing a documentation template is certainly the most important step in the process of documentation generation and the quality of the documentation depends directly on it. This activity is carried out by a combined use of DTE and DAC. DAC prepares and integrates DGML scripts into the template, and DTE formats documentation attributes and inserts content independent of scripts.

When integrating DGML scripts, the Wizard can be a great help. All you have to do is form a report and select an object, that is form a documentation object and then specify in the Wizard which information on the documentation object you want to document. On the basis of this selection, the Wizard create an adequate DGML script. If you click the Add to Template button, the Wizard will insert this block of DGML scripts into the active documentation template at insertion point position, and if you click the Copy Script button, then the DGML script block will be transferred to the Clipboard.

If you have transferred the DGML script block to the Clipboard, you can later transfer it somewhere else using the Paste (Ctrl-V) command in DTE.

DGML scripts created by the Wizard according to your specification will be clearly set apart in the documentation template by a pair of #{ characters for the beginning and a pair of }# characters for the end of the DGML script. You can simply delete the entire block and repeat the process of integrating DGML scripts using the Wizard.

Documentation Object

A documentation object is anything you can select in DAC and for which you can form documentation. The following can be documentation objects:

DAC reports

Browser reports

Declarations, Uses, Assignment, CallsTo, CallsWithin, UsesWithin, Global <Symbols> and Search.

VCS reports

VCSHistory and VCSDifference.

Graphics reports

FlowChart, CallGraph, TypeGraph and Metrics.

Project data

Data on the project itself

Project, including VCS data

Project object data

File, including VCS data, Directory, Group, View, <Symbol>, where <Symbol> can be Function, Variable, Constant, Type and Macro.

Messages

Wizard

The Wizard is a visual DG tool used to automate the DT creation process, i.e. the process of creating those parts of DT written in DGML language, so that even if you are not familiar with DGML, you can create DTs.

Wizard is accessed via the Wizard command in the Documentation menu, and the content displayed in Wizard depends on the DAC context at the moment of starting. The DAC context means the DAC selection or report whose window has focus.

In most cases, one DAC context can be documented in several ways. For example, if in the editor the pointer sits on some symbol name, then, you can document the symbol itself, but also the file you are editing, and the like. Therefore, every DAC context has a corresponding set of documentation objects. The Wizard offers you to choose one documentation object, for which you want to create DGML script which you will use to document it

For every documentation object the Wizard generates the corresponding data retrieving script. The script results in the DGML variable of the corresponding type. Therefore, in the case of the previously mentioned editor file, the result of the data retrieving script is a variable of the DGML type TFile. If the documentation object is a collection, for example, a collection of global functions, then, the result of the data retrieving script will be again a variable of the corresponding DGML type, but the documenting of this variable will be carried out in the for_each loop, which will be, of course, generated by the Wizard. The data retrieving script itself does not generate documentation, but it only prepares DGML variables, on the basis of which the documentation will be generated.

Documentation Wizard dialog box

The Wizard forms a set of DGML scripts on the basis of your choice of information, on the selected object of documenting. These scripts are then inserted into some of the active DTs or into the Clipboard, as it has already been explained. The subset of information on the object of documenting is chosen by selecting a set of properties displayed on the property list.

The properties on the list can be simple or composite. Each simple property contains only one OD data item (e.g. file size if the OD is a particular file). Composite properties can contain several properties, either simple or composite, so it is necessary, when choosing some of the composite properties, to provide additional specification which of the internal properties is to be documented.

The Wizard dialog box displayed above has the following parts:

Documentation object - The content displayed here depends on DAC context at the moment of starting the Wizard. A more detailed account of the connection between DAC context, documentation object, its list of properties and DGML Scripts is provided in the "Appendix D - DGML script".

Property tree - This tree contains all the information on the documentation object which you selected on the property list and which will appear in the generated documentation. On the basis of this tree, the Wizard forms a DGML script block. When the Wizard appears, the tree only has a root whose name is identical to the name of the OD being documented. You add properties to the tree by selecting them from the property list. If you select a composite property on the tree, all the properties it contains can be seen on the property list. As a simple property contains no other properties in itself, selecting it on the tree displays on the property list properties related to the parent property on the tree. The order in which items appear on the tree is important for how the documentation will look. Documentation will be generated in the order specified in the tree. You can change this order using the Up and Down buttons. Using these buttons you can change the position of the selected property in the Property tree in relation to other properties on the same hierarchical level.

Property list - All information on the selected property on the property tree which you can integrate into the documentation is found on this list. The list has the following columns:

Property - You insert a property onto the Property tree by selecting the check box preceding the property on the Property list .

Label - In this column you can enter text which will appear before the property value in GD.

Options - In this column you can select additional information on the documentation object.

Instead of the property list in the Wizard for properties of the graphics type, a group of options displayed in the next figure appears:

Documentation Wizard Image properties

Image properties for OD and properties of the graphics type (FlowChart, CallGraph, TypeGraph, Metrics, MetricsLegend):

Use colors - determines whether the documented image will have color or whether it will be grayscale.

Crop- determines whether extra white space around the image borders will be cropped in the generated document

Fit to page - determines the maximal size of the image that is to be integrated into DT, and after that, into GD as well.

Custom Size - determines the size of the image that is to be integrated into DT, and after that, into GD as well.

Mosaic - the documented image will be divided into segments whose dimensions are defined in the Size property.

Draw Borders - option enables the framing of the documented image and the marking of the lines that should be cut in order to make a picture out of mosaic parts

Label - enables generating at the top of the mosaic image a label displaying the coordinates of each of the generated mosaic parts.

Wizard Example for Textual Reports

The documentation object is, at the same time, the root of the Wizard property tree. Every non expandable node in the property tree has a corresponding DGML type variable. These variables are, depending on their type, documented by their simple and composite properties. Simple properties are related to the information which cannot be further structurally decomposed, and for which the Wizard generates simple script which, in the generation process, produces information in the generated document. A composite property is the information which can be documented using several properties (simple or composite). For a composite property, as well as for the documentation object, the Wizard generates only the data retrieving script, which results in a corresponding DGML type variable. This means that the whole documentation is generated by simple property scripts, while data retrieving scripts only prepare data which are to be integrated into the generated document.

Documentation Wizard property tree

Above figure shows an example of the Wizard property tree. The function HardwareInit has been chosen as the documentation object. It has been chosen that this function is to be documented by the simple property Name, and the composite properties Parameters and File. It has been chosen that the composite property Parameters will be documented by its simple property Type, and that the composite property File will be documented by its simple property ProjectName. On the basis of the property tree specified in this way, the Wizard will generate the following DGML script (without ordinal line numbers, which have been shown for the purposes of reference).

1: #{ /* DG-Wizard generated block */ }#\
2: #{ GetFunction(TFunctionData, "HardwareInit", "Control\HrdwInit.c") }#\
3: #{ /* use TFunctionData */ }#\
4: #{ TFunctionData.Name }#
5: #{ for_each (TSymbolData1 in TFunctionData.Parameters) }#\
6: #{ /* use TSymbolData1 */ }#\
7: #{ TSymbolData1.Type }#
8: #{ end_for }#\
9: #{ GetFile(TFileData1, TFunctionData.FileName) }#\
10: #{ /* use TFileData1 */ }#\
11: #{ TFileData1.ProjectName }#
12: #{ /* end DG-Wizard generated block */ }#\

Lines 1 and 12 of this script are comments which in the DT single out the script generated by the Wizard.

Lines 2 and 3 contain the data retrieving script of the documentation object - the function HardwareInit. This script prepares the TFunction type variable TFunctionData.

In line 4 there is the script generated for the simple property Name. In the generated document, this script creates the name of the function - that is, HardwareInit.

Lines 5,6 and 8 contain the data retrieving script for the composite property Parameters. Since Parameters is a collection, the Wizard has generated the for_each loop, and within the loop the variable TSymbolData1 is ready to be used. It is used by the simple property Type, on the basis of which line 7 is generated ( #{ TSymbolData1.Type }# ).

Lines 9 and 10 represent the data retrieving script for the File property, which prepares the variable TFileData1 used by the script generated for the simple property ProjectName.

Wizard Example for Graph Reports

There are several graphic-type documentation objects:

Flowchart
CallGraph
TypeGraph
Metrics

All graphic ODs have the same (simple) properties:

Use colors
Mosaic
Border
Width
Height

The general form of DGML scripts to be generated by the Wizard:

#{< DTMLscript(<image_variable_symbolic>) >}#
#{FormatColor(<image_variable_symbolic>, <color_param_string>) }#
#{FormatCrop(<image_variable_symbolic>, <crop_string>) }#
#{FormatAsMosaic(<image_variable_symbolic>, <dimensin_X>, <dimenssion_Y>) }#
#{FormatBorder(<image_variable_symbolic>, <border_param_string>) }#
#{begin_image(<image_variable_symbolic>)}#
   <WMF image>
#{end_image}#

where:

< DTMLscript(<image_variable_symbolic>) >
- DGML script generated according to data in the table above,

<image_variable_symbolic> - output variable which identifies the generated graphic OD,

Format(...) - DGML scripts for formatting one or more figures. It is formed on the basis of properties Use Colors, Mosaic and Border.

#{begin_image(<image_variable_symbolic>)}# and #{end_image}#
- limit the block connected to the figure. Everything within this block pertains to the figure with the reference ImageVar. You can find the DGML functions SegmentX() and SegmentY() here.

<WMF image> - place where the figure (the formed graphic report) is inserted in WMF (Windows Meta File) format. It is used only for formatting in DTE. During the generation phase, it will be replaced by the current graphic report.


Copyright 1993-2017, RistanCASE GmbH