<< Click to Display Table of Contents >>   Scripts Documentation

The Scripts Documentation tool helps users to organize and document application's scripts. Users can access this tool in the following ways:

•By clicking on the Default toolbar. With this option, all Domain scripts are stored in a file

•By right-clicking project's or object's name and selecting the Document scripts option. With this option, only scripts from this object and its child objects are stored in a file

 

This tool generates a text file that can be edited in any text editor. A documentation file is formatted with a wizard called Script Documentation Wizard. This wizard helps users to configure a scripts documentation file.

The Documentation file window defines information about a file that stores application scripts.

Type the name of a file where documentation scripts are generated in the Filename option. Specify a place where this file must be saved in the Save file in folder option, and, if necessary, click Browse.

Click Next and go to the next window.

The File formatting window allows users to format this file with script information. They can choose between a simplified documentation, containing only script names, or a complete documentation, containing the whole script code.

For example, consider the following script.

Sub InitialScreen_KeyDown(KeyCode, Shift)
  If (KeyCode = 27) Then
    Application.Exit
End Sub

 

If the selected option is Only the script name, the following text is stored in this file.

InitialScreen_KeyDown(KeyCode, Shift)

 

If, however, the selected option is The whole script, then this code is stored with the same user-defined format, such as indentation and blank lines, in Scripts Editor.

Regardless of the selected format, an identifier containing an object name is stored before saving this script, to avoid conflicts. Consider for example the next objects.

InitialScreen
  CommandButton1
Screen1
  CommandButton1

 

Both scripts, considering the same Click event, would be CommandButton1_Click(). Thus, saving the first object in the file would be in the next format.

<InitialScreen.CommandButton1:CommandButton1_Click()>
Sub CommandButton1_Click()
  ...
End Sub

 

And for the second object the format would be as in the next example.

<Screen1.CommandButton1:CommandButton1_Click()>
Sub CommandButton1_Click()
  ...
End Sub

 

This allows correctly identifying each script. Click Next to go to the next window.

On the Scripts separator window, users can define a text that is stored between scripts in a documentation file. Users can select between blank or customizable lines, and also inform how many of these lines are inserted into this file.

Users can select a Blank line or a Customizable line. If they select the Blank line option, the documentation file has a blank line between each script. If they select the Customizable line option, then they can inform one or more characters to compose the line used as a script separator. These characters are informed in the Type line text option. If they select the Repeat until the end of the line option, the informed characters are repeated up to the line's size limit, which is 80 characters. Users can also use more than one line as a separator, blank or customizable. Just inform a number between 1 (one) and 100 in the Type number of lines of separator option. Click Next to finish the configuration. After that, this wizard shows a message indicating that both configuration and generation of the file containing scripts documentation are finished.

Some relevant observations:

•XControl, XFolder, and XObject scripts are saved only once in a file, because they are found during library search. Instance scripts are stored when an instance's parent object is searched

•Picks are internally scripts. Therefore, they are also documented

•File storage is performed alphabetically per object name, inside every project or library

•Users cannot add scripts to an existing file via Wizard. Every time this Wizard is started, a new file is created. In case it already exists, it is overwritten

•This tool may take a while to generate a documentation file, in case the application is too large and the search involves many types of objects. To improve a search, try generating a file for each Elipse E3's object type