Back in the days of mainframes and very formal centralized management information systems (MIS) departments, documentation was a mandatory requirement for the completion of an application. Today, it seems as though all types of people are developing applications: administrative assistants, CEOs, sales managers, MIS professionals, and so on. To make matters worse, many of us who consider ourselves MIS professionals never received any formal systems training. Finally, the demand to get an application up and running and then to move on to the next application is more prevalent than ever. As a result of all these factors, it seems that documentation has gone by the wayside.
Despite all the reasons why documentation doesn’t seem to happen, properly documenting your application is as important today as it was in the mainframe days. Documentation provides you and your users with these benefits:
This chapter covers the various ways in which you can document your application objects and code.
Fortunately, Access ships with an excellent tool to assist you with the process of documenting your database: the Database Documenter. Although you can use this tool without special preparation on your part, a little bit of work as you build the components of your application can go a long way toward enhancing the value of the Database Documenter’s output.
The Database Documenter prints all field and table descriptions that you enter in the design of a table. Figure 29.1 shows a table in Design view. Notice the descriptions for the ClientID
and StateProvince
fields. These descriptions provide additional information that is not readily obvious from looking at the field names. The Table Properties window also contains a Description
property. This Database Documenter includes this property when you print the table’s documentation.
Figure 29.1. The descriptions that you include for each field appear in the Database Documenter.
Entering a table description also assists you and the users of your database when you are working with the tables in the database. Figure 9.2 shows the Navigation Pane after I entered table descriptions. The description of each table appears in the Navigation Pane. If the descriptions don’t appear, you may need to adjust the View setting to View By Details to see the descriptions.
Figure 29.2. The description of each table appears in the Navigation Pane.
Just as you can enhance the output that the Database Documenter provides for tables, you also can enhance the output it provides for queries. Figure 29.3 shows the Query Properties window. I filled in the Description
property with a detailed description of the purpose of the query. Figure 29.4 shows the description of an individual column in a query. Access includes both the query and field descriptions in the output provided by the Database Documenter.
Figure 29.3. The Description
property shows a detailed description of the purpose of the query.
Figure 29.4. You can also describe an individual column in a query.
Documentation is not limited to table and query objects. A form also has a Description
property. You cannot access it from the Design view of the form, though. To view or modify the Description
property of a form, follow these steps:
Figure 29.5. You can use the Object Properties dialog box to document each object in the database.
Figure 29.6. The Navigation Pane shows a description of a form.
You document reports in exactly the same manner as forms. Reports have a Description
property that you must enter in the Object Properties dialog box. Remember that to access this dialog box, you right-click the object in the Navigation Pane and then choose Properties.
You can document macros in significantly more detail than forms and reports. You can document each line of the macro, as shown in Figure 29.7. Not only does this provide documentation in the Database Documenter, but macro comments also become code comments when you convert a macro to a Visual Basic module. In addition to documenting each line of a macro, you can add a description to the macro. As with forms and reports, to accomplish this, right-click the macro from the Navigation Pane and choose Properties.
Figure 29.7. You can document a macro by including a description of what each line of the macro does.
I cannot emphasize enough how important it is to document your modules with comments. Of course, you do not need to document every line of code. I document all areas of my code that I feel are not self-explanatory. Comments assist me when I revisit the code to make modifications and enhancements. They also assist anyone who is responsible for maintaining my code. Finally, they provide the user with documentation about what my application is doing. Comments print with your code modules, as shown later in this chapter in the section “Using the Database Documenter.” As with the other objects, you can right-click a module to assign a description to it.
In addition to enabling you to assign descriptions to the objects in the database, Microsoft Access enables you to document the database as a whole. You do this by filling in the information included in the Database Properties window. To access a database’s properties, click the Microsoft Office Access button and select Manage. Choose Database Properties from the Manage cascading menu. The Database Properties dialog box appears, as shown in Figure 29.8. As you can see, it is a tabbed dialog box; tabs include General, Summary, Statistics, Contents, and Custom.
Figure 29.8. The Database Properties window shows the General properties of a database.
Descriptions of the tabs in the Database Properties dialog box follow:
Figure 29.9. The Summary tab of the Database Properties dialog box contains modifiable information that describes the database and what it does.
Figure 29.10. The Contents tab of the Database Properties dialog box includes a list of all the objects contained in the database.
The Database Documenter is an elegant tool that is part of the Access application. It enables you to selectively produce varying levels of documentation for each object in your database. To use the Database Documenter, follow these steps:
Figure 29.11. You can use the Documenter dialog box to designate which objects you want to document.
To document all objects in the database, click the All Object Types tab and then click Select All.
Access can produce a very large volume of documentation, particularly if you select numerous objects. For this reason, you should carefully select the objects that you want to document. Make sure that, after you preview the results, you verify that you got what you expected before you print volumes of meaningless documentation.
To document the properties of the database or the relationships between the tables in the database, click the Current Database tab and select Properties or Relationships.
After you select all the desired objects and options and click OK, the Object Definition window appears. You can use this Print Preview window to view the documentation output for the objects you selected (see Figure 29.12). This Print Preview window is just like any other Print Preview window; you can view each page of the documentation and send the documentation to the printer.
Figure 29.12. The Object Definition Print Preview window allows you to view each page of the documentation and send the documentation to the printer.
The PDF/XPS option may not appear on your toolbar. It is a downloadable feature that you must obtain from Microsoft’s website. You can access it via help under the topic “Enable support for other file formats, such as PDF and XPS.”
By default, the Database Documenter outputs a huge volume of information for each selected object. For example, the Database Documenter documents each control on a form, including every property of the control. You can easily produce 50 pages of documentation for a couple of database objects. Besides being a tremendous waste of paper, this volume of information is overwhelming to review. Fortunately, you can refine the level of detail provided by the Documenter for each category of object you are documenting. Just click the Options button in the Documenter dialog box.
Figure 29.13 shows the table definition options. Notice that you can specify whether you want to print table Properties, Relationships, and Permissions by User and Group. You also can indicate the level of detail you want to display for each field: Nothing; Names, Data Types, and Sizes; or Names, Data Types, Sizes, and Properties. For table indexes, you can opt to include Nothing; Names and Fields; or Names, Fields, and Properties.
Figure 29.13. You can use the Print Table Definition dialog box to designate which aspects of a table’s definition Access will document.
If you select the Queries tab in the Documenter dialog box and then click Options, the Print Query Definition dialog box appears, as shown in Figure 29.14. Here, you can select the level of detail the Database Documenter will output for the selected queries. You can choose whether to include Properties, SQL, Parameters, Relationships, and Permissions by User and Group for the query. You also can select the level of detail for each column of the query and for the indexes involved in the query.
Figure 29.14. You use the Print Query Definition dialog box to designate which aspects of a query’s definition the Database Documenter includes in the output.
The Form and Report options are similar to one another. Figure 29.15 shows the Print Form Definition dialog box. Here, you can specify whether you want to print Properties, Code, and Permissions by User and Group for a form. For each control on the form, you can choose to print Nothing, the Names of the controls, or the Names and Properties of the controls. The Print Report Definition dialog box offers the same options. Both dialog boxes offer a Properties button, used to designate the categories of properties that the Database Documenter prints. You can opt to print Other properties, Event properties, Data properties, or Format properties.
Figure 29.15. You use the Print Form Definition dialog box to designate which aspects of a form’s definition the Database Documenter includes in the output.
For macros, you can choose whether you want to print macro Properties, Actions and Arguments, or Permissions by User and Group. For modules, you can choose to view Properties, Code, and Permissions by User and Group.
As you can see, the Database Documenter gives you great flexibility in the level of detail it provides. Of course, if you haven’t filled in the properties of an object (for example, the description), it does you no good to ask the Documenter to print those properties.
After you produce the documentation and it appears in the Object Definition Print Preview window, you can output it to other formats. When the Print Preview window is active, the Print Preview tab appears (see Figure 29.16). The Data group provides you with several options for exporting your report. You can export to a PDF file, XPS file, Word document, Text file, Access database, XML file, Snapshot file, or HTML document! Depending on the option that you select, the next step varies. For example, if you opt to send the file to Microsoft Word, the Export – RTF File dialog box appears (see Figure 29.17). Here, you designate the destination and export options for the file.
Figure 29.16. The Print Preview tab allows you to output your documentation to other formats.
Figure 29.17. Using the Export – RTF File dialog box, you can select the export options for Microsoft Word.
Microsoft added a wonderful feature in Access 2003. It provides the capability to view information about object dependencies. Here’s how it works:
Figure 29.18. You must invoke the Track name AutoCorrect info option for dependency information to appear.
Figure 29.19. The Object Dependencies pane allows you to view an object’s dependencies.
tblProjects
.
Figure 29.20. The Object Dependencies pane shows you the objects that depend on the selected object, as well as objects that the selected object depends on.
Most of the time, the options that the Database Documenter provides are sufficient. At times, you won’t like the format that the Database Documenter selects—or, more importantly, you might want to document properties of the database objects not available through the user interface. In these situations, you can choose to enumerate the database objects using code and output them to a custom report format.
Using ADOX (ADO Extensions for DDL and Security), you can enumerate any of the objects in your database. Listing 29.1 shows an example.
Listing 29.1. Using ADOX to Enumerate the Table Objects in a Database
For the code in Listing 29.1 to run, you must first set a reference (via Tools, References) to the Microsoft ADO Ext 2.7 for DDL and Security library.
The EnumerateTables
routine, located in the basDocument
module of CHAP29EX.ACCDB
on the sample code website, documents various information about the tables in the database. It uses the ADOX catalog and table objects and a For...Each
loop to loop through all the table definitions in the database. For each table in the database, it determines whether the table’s type property is set to "Table"
, indicating that it is a standard table (as opposed to a system table or a query). It then uses the Execute
method of the Connection
object to execute a SQL statement, inserting all the requested information about the table definition into a table called tblTableDoc
. You can use this table as the foundation for a report. Of course, when you use appropriate For...Each
loops and properties, along with the ADOX
object model, you can obtain any information about any of the objects in the database using the same technique.
Practice using various options in the Database Documenter for your own applications. As you change the options for each object type, view the output differences. If you are particularly ambitious, try writing some code to enumerate the objects of the database.
Documentation is a necessary part of the application development process; fortunately, Microsoft Access makes documenting your application easy. This chapter covered the object Description properties Access provides, as well as the extremely powerful Database Documenter. It also covered a feature related to documentation called Object Dependency. Finally, the chapter highlighted how you can create your own documentation using ADOX and custom reports. Using any combination of the techniques covered in the chapter, you can produce complete documentation for all aspects of your application.
3.144.94.187