Auto-generation of customizable documentation for application files based on file content.
Original Publication Date: 2001-Apr-01
Included in the Prior Art Database: 2003-Jun-20
In any application, maintaining current and accurate documentation about the code containied within that application can be a cumbersome duty, and is therefore often overlooked. Whenever a source code file is modified, potentially changing function, the documentation should reflect this change in order to be accurate and useful. When the documentation is kept in a separate location (a separate file, at minimum, or at worst, an entirely separate medium), it becomes more likely that it will not be updated when code is changed. An additional problem that arises from separation of code and documentation is that a person looking directly at the code would have to go through extra steps (locating and opening separate files) to see the documentation, and this wastes time and resources. The first part of this solution is to contain the essence of the documentation within the code itself, where it can be easily updated and viewed by developers. The second part of this solution is to have a utility that will extract this documentation from the code and create customizable documentation reports which are updated, accurate, and readily available. To solve this problem, a special set of comments appears within each source code file. These comments can be of several varieties, and explain or list essential processes or elements of the individual file. If these comments appear at the beginning of the file, then they are easily viewed whenever the file is opened, and can be easily located, read, and modified by code developers. This part of the solution provides for easy access to documentation by the developer. To retrieve the comments from all of the source code, a program is created which scans the source code files. Looking for these special comment types, the program can extract the comments and create full documentation for the application. In addition, the program has options which allow the resulting documentation to be customizable. With these customizations, the user can choose to analyze all files, or a subset of files. He can also choose to have all comment types extracted, or just certain ones. With this tool, a distinct advantage is achieved in that anyone can run one program to generate exactly what he needs to know about any set of files within the application. Any project can have problems within maintaining documentation. Many solve it by using Notes databases, or other documentation sources, but these all depend on the developers making the effort to go into the documentation after code modifications, to record the changes that were made. This extra step tends to be too much for a busy developer. Large documentation resources such as databases can also be unwieldy when they contain everything there is to know about the entire application. For this reason, many might steer away from the idea of having to sort through pages of information in order to find out details about a small set of code. My solution avoids that problem because you can create customized documentation reports for exactly what you need to know. I developed and implemented this solution for the IBM internal application called infoPORT. This application contains hundreds of Net.Data macro files, which were stored on a remote server. By adding the special comments to each file, I was able to have all of my documentation containied with the code. When full documentation was requested, it could be easily generated in a matter of seconds with the comment-extraction program. When I began training a new developer to take over the application, the comment-extraction program was an invaluable tool. It enabled us to quickly generate custom reports for sets of files, to answer very specific questions such as: "which of the business files used business name as an input?" "which of the files use a translation function?" "what are the names of all the help files we use for the intelligence reports?" The concept behind this comment-extraction program is that you can specify certain properties that you are searching for, in order to create lists of information about individual files. This program can be enhanced or modified for a particular application in order to be more suited to the possible needs of the development or management team.