Browse Prior Art Database

Auto-generation of customizable documentation for application files based on file content.

IP.com Disclosure Number: IPCOM000014730D
Original Publication Date: 2001-Apr-01
Included in the Prior Art Database: 2003-Jun-20
Document File: 3 page(s) / 46K

Publishing Venue

IBM

Abstract

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.

This text was extracted from a PDF file.
This is the abbreviated version, containing approximately 38% of the total text.

Page 1 of 3

  Auto-generation of customizable documentation for application files based on file content.

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 i...