Documentation Generator Tutorial
To familiarize you with its basic possibilities, you will be walked, step by step, through several typical scenarios for using DG:
Generating Documentation from a Standard Template
Generating a Document from an Adapted Template
Using the Wizard to Create Your Own Template
Generating Documentation from a Standard Template
1. You can start generating documentation using the Documentation > Generate Documentation menu command. Dialog will appear, enabling you to select the template on which the generated document will be based. The name of the recently used or currently open templates will appear on the list if you have already generated documentation, or have a template file open in Microsoft Word. Select the standard template ModuleDocumentation.rtf. If the list is empty, or this template does not appear on the list, click Browse and select the ModuleSummary.rtf template, which resides in the "Standard Documentation Templates" folder within the DA-C program folder.
Choose Documentation Template dialog
Note: It is possible to change the behavior of the Documentation > Generate documentation command in the dialog brought up by the Options > Documentation command, using the Generate item of the Generating tab.
2. Click Generate to initiate the process of documentation generation on the basis of the selected template. The process begins with an update of the SCA database. The documentation generation status can be monitored in the dialog shown. Once the document has been generated, click OK to close the status dialog. Information messages and possible errors during the documentation generation process will be reported under the Documentation Generator tab of the DA-C Message Logs.
3. The generated document, whose name is identical to the name of the template with the suffix Document is open in Microsoft Word. The document was automatically added to the active project (this behavior can be changed using the Options > Documentation command) in the Project Explorer Default (types) \ Document Files logical group.
Documentation Generator Status dialog
Generating a Document from an Adapted Template
With some documents based on Standard Documentation templates, you are expected to fill in certain sections of the document manually. Although this is always possible in a generated document, it is not a good strategy as the changes entered will be lost the next time a document is generated from the same template. The following scenario ensures that content entered manually is retained the next time a document is generated from the same template:
1. Using the Documentation > Open Template command, open the standard template of your choice in Microsoft Word.
2. Save the template under a different name and/or in a different folder so as to retain the standard template in unaltered form. You can achieve the same effect by activating the Documentation > New Template command in step one and selecting the template of your choice from the Standard Documentation Templates list.
3. In the open template, fill in with text all the sections intended (replace italicized blue text with your own text). Save the changes.
4. Generate the document following the procedure described in "Generating Documentation from a Standard Template".
5. Each time project data is changed, repeat the document generation procedure with a customized template, at which time data from the project will be updated in the document generated. If you want to update the sections entered manually, enter the changes in the template and generate the document.
Using the Wizard to Create Your Own Template
Standard Documentation templates offer several ready-made solutions for your project documentation. If you have specific demands and want to change the content of a standard template or create your own, the Documentation Wizard will help you a great deal. For example, if you would like a document in which all project modules are entered together with a list of the names of functions defined within a particular module for each of the modules. The following scenario describes creating a corresponding template:
1. Using the Documentation > New Template command, open a new, empty template in Microsoft Word.
2. In the Project Explorer's Logical View, select the C Source Files folder.
3. Using the Documentation > Wizard command, activate the Documentation Wizard for creating documentation scripts.
4. The following entry should appear in the Documentation Object list (whose content depends on the content active in DA-C at the time of carrying out the Documentation > Wizard command):
Directory: LR:\Default (types)\C Source Files\
indicating that, in terms of documentation, you are interested in the content of the identically named project file logical group.5. The same content appears in the left pane (Property Tree). Select this content and on the list to the right (Property List) check the Files item. The same item will appear in the left pane.
6. Select Files in the left pane. On the list to the right, the content is changed to reflect file properties of interest for documentation. At this time, the Wizard looks as in following figure:
Documentation Wizard dialog
7. Check a property on the list.
Note: Elementary properties, such as Name, are represented by a yellow icon. It is sufficient to select them in order for them to appear in the generated document.
8. Check the Functions property on the list. This property is a composite property and is represented by a three-color icon. The item Functions, which you should select, appears in the left pane. The content of the list on the right changes, displaying a set of properties which belong to this composite property. On the list to the right, check the Name property.
9. Click the Add To Template button. In the template file open in Microsoft Word, the Wizard will insert the following script code:
#{ /* DG-Wizard generated block */ }#\
#{ GetDirectory(TDirectoryData, "LR:\Default (types)\C Source Files\") }#\
#{ /* use TDirectoryData */ }#\
#{ for_each(File in TDirectoryData.Files) }#\
#{ GetFile(TFileData1, File) }#\
#{ /* use TFileData1 */ }#\
#{ TFileData1.Name }#
#{ GetModuleFunctions(FunctionDataCol, TFileData1.FullPath) }#\
#{ for_each(TFunctionData1 in FunctionDataCol) }#\
#{ /* use TFunctionData1 */ }#\
#{ TFunctionData1.Name }#
#{ end_for }#\ #{ end_for }#\
#{ /* end DG-Wizard generated block */ }#When generating documentation, in the external for_each loop, iteration is carried out through the
TdirectoryFilescollection, that is through all files of the C Source Files logical group. For each file, iteration is carried out through theFunctionDataColfile collection, on which the translation of the file viewed depends (internal for_each loop).Any visible effect in the generated document is created by the script
#{ TFileData1.Name }#
which inserts the name of the .C file into the document
#{ TFunctionData1.Name }#
and which inserts the name of the function defined in the .C file viewed in the document.
Additional formatting can be applied to the template by direct editing in Microsoft Word. For example, if you would like the name of each module to precede an empty line and the word Module, as well as to be underlined or written in bold face, the word Functions, and then the names of the module functions indented one TAB character and italicized, to follow the name, you will apply the corresponding formatting so that the template text looks like this:
#{ /* DG-Wizard generated block */ }#\
#{ GetDirectory(TDirectoryData, "LR:\Default (types)\C Source Files\") }#\
#{ /* use TDirectoryData */ }#\
#{ for_each(File in TDirectoryData.Files) }#\
#{ GetFile(TFileData1, File) }#\ #{ /* use TFileData1 */ }#\
Module #{ TFileData1.Name }#
Functions: #{ GetModuleFunctions(FunctionDataCol, TFileData1.FullPath) }#\
#{ for_each(TFunctionData1 in FunctionDataCol) }#\
#{ /* use TFunctionData1 */ }#\
#{ TFunctionData1.Name }#
#{ end_for }#\
#{ end_for }#\
#{ /* end DG-Wizard generated block */ }#The generated document will look like this:
Module newone.c
Functions:
f1
main
Module file2.c
Functions:
f2
If you would like to familiarize yourself with other DG possibilities not mentioned in the previously described scenarios, you can consult the User Manual and Reference Manual.
Copyright © 1993-2022, RistanCASE PR