Documenting Wizard
The Documenting wizard formats and produces text files from your code in projects and program files. You can use these files to share the code or to more easily read large sections in projects and programs. For example, the wizard can produce files containing indented source code, capitalized reserved words and variables, and can also produce a report of the keywords in the program.
**Note **The wizard does not modify your code and only creates a text file to document the code.
You can customize the way the Documenting wizard works by adding certain directives to your code. For more information, see Customizing the Documenting Wizard.
To access the Documenting wizard
- From the Tools menu, choose Wizards, and click Documenting.
Step 1 – Choose Source File
In this step, you can enter the name of a project file or a specific program file. If you choose a project file, the Documenting wizard documents all the programs in the project, including the event code for forms, class library code, and so on.
Step 2 – Set Capitalization
In this step, you choose how the Documenting wizard should capitalize keywords and symbols in the text file of your code. Keywords are all the reserved words in the Visual FoxPro programming language, such as MODIFY. Symbols are the variables and names that you define in your code. Capitalization makes it easier to read and identify elements in your code. The capitalization options are:
- UPPERCASE
Keywords and symbols are displayed in all uppercase letters. - lowercase
Keywords and symbols are displayed in all lowercase letters. - MixedCase
Keywords are displayed with the first letter of each word in the keyword capitalized, for example, AddObject. - Match first occurrence
Symbols are displayed according to the capitalization of the first occurrence in the file. For instance, if you use initial capitals in the first occurrence in a file, all other occurrences of those keywords are displayed the same way, no matter how they might be typed in subsequent occurrences. - No change
Keywords and symbols are not modified.
Step 3 – Set Indentation
In this step, you specify how the Documenting wizard will indent lines in the text file of your code. The wizard can indent specific types of lines, and you can adjust how many spaces to use when indenting. Functionally, in code, there is no difference between spaces or tabs. Indenting makes it easier to read and understand your code.
- Type of Indent
Choose whether the wizard should indent using tabs or spaces. To turn off indentation, choose No Change. If you choose Spaces, then you must select the number of spaces to be used. If you choose Tabs, then the Documenting wizard uses the current Visual FoxPro tab setting. - Text to indent
Specify the type of line that the wizard should indent. Your choices are Comments, Controls structures (such as loops, IF blocks, and DO CASE structures), and Lines continued by a semi-colon (statements that are split across multiple lines).
Step 4 – Add Headings
In this step, you specify where, if anywhere, you want the Documenting wizard to insert headings into the text file of your code. Headings are comments about the code that are relevant to the code that they precede. They can be placed at the beginning of files, procedures, class definitions, and methods to make your formatted code more understandable.
Step 5 – Select Reports
In this step, you specify the types of reports that the Documenting wizard creates. (The reports are actually text files.) The wizard can produce the types of reports listed in the following table.
| Report Type | File Name | Remarks |
|---|---|---|
| Action Diagram | project.act | Shows the hierarchical relations within your code. If you are not working with ASCII code page 1250 and ANSI code page 1252, see the directive "*# document ACTIONCHARS" in Customizing the Documenting Wizard. |
| Cross-Reference | Xref.lst | Lists all the user-defined symbols. |
| File Listing | Files.lst | Lists all the files in the project. |
| Source Code Listing | project.lst | Puts all formatted code in a single file. |
| Tree Diagram | Tree.lst | Shows the procedure calling tree. |
The wizard also automatically creates the following files:
- **Files.dbf **Table with a record for each file in the project.
- Fdxref.dbf Table with a record for each instance of user symbols (as listed in the following table) in the code. This table makes it possible for you to see what type of Visual FoxPro element is represented by each symbol.
Fdxref.dbf contains a field named Flag for identifying the keywords. The identifiers are the following.
| Flag | Description |
|---|---|
| B | Base class |
| C | Class name |
| D | Defined PROCEDURE or FUNCTION (not method) |
| F | Function call: myproc( ) or DO myproc |
| K | Keyword |
| M | Method definition |
| N | Name of file |
| O | Object |
| P | Property of an object |
| R | User symbol reference |
| V | User symbols (variable) definition (PARA, PRIV, PUBL, DIME) |
Step 6 – Finish
In this step, you can determine the location and structure that contains your code document. You also can specify whether the current document overwrites any previous documents.
By default, the wizard does not overwrite your existing files. Specify Overwrite existing files to overwrite your existing code files with the new ones that the wizard saves.
You can choose to have a single directory in which the wizard will save all the files, by selecting the Place files in a singledirectory option. When you click Finish, the wizard will prompt you to choose a directory that it creates.
To choose a new directory that will contain the full project tree of your project, select the Place files in a new directory tree. When you click Finish, the wizard will prompt you to choose a directory where it will create a copy of the project's source tree and save the new, formatted program files in the appropriate directories of the new tree.
When you select Cross-reference keywords, the wizard creates or adds to Fdxref.dbf, the table of keywords mentioned earlier. After running the wizard, you can use the table to create reports of the keywords you are using in your application. The wizard adds one record to Fdxref.dbf for each instance a of Visual FoxPro keyword in your code.
In addition, when this option is selected, the wizard matches keywords in your code with the first field, named Token, in the Fdkeywrd.dbf file. This file can be found in the ..\Wizards folder of the Visual FoxPro root directory and contains all the Visual FoxPro reserved words. The second column, Code, in Fdkeywrd.dbf contains an identifier that tells the wizard how to treat the keyword when analyzing your code. The following table describes the identifier codes.
| Code | Description |
|---|---|
| I | Indent |
| U | Un-indent (remove indent) |
| R | Reset indentation to 0 (or 1 if in DefineClass) |
| F | Procedure or function |
| D | While or Case: DO clause |
| O | Object (Spinner, CommandButton) |
| P | Property (Scalemode, DecimalPoints) |
| M | Method (Init, KeyPress) |
| C | ClauseUsed only as a Clause: can't start a statement |
Note Depending on the size of your code, this option might enlarge Fdxref.dbf by a large number of records. Before running the wizard and choosing the option to create keyword cross-references, be sure you have enough disk space.
When you select Run analyzer, the wizard starts the Visual FoxPro Code Analyzer, which dynamically traces the structure and symbols in Visual FoxPro application files. Code Analyzer provides visual controls, a menu, and keyboard options to navigate through the text file of your application file code by using output from the Documenting wizard.
See Also
Customizing the Documenting Wizard | Wizards Overview | Code Analyzer