Automatically connecting documentation to code with rose

ABSTRACT

One of the most common problems with program documentation is keeping it synchronized with the source code it purports to explain. One solution to this problem is to automate the documentation process using reverse engineering technology. Reverse engineering is an emerging branch of software engineering that focuses on recreating high-level information (such as program documentation) from low-level artifacts (such as source code). This paper describes an automated approach to maintaining the connection between documentation and code by leveraging the reverse engineering capabilities built-in to Rational Rose. The approach produces application programming interface documentation for component object model-based (COM) dynamic link libraries (DLLs), C++ source code, and Java archive files. The documentation is always accurate and up-to-date. A primary advantage of the approach is its reliance on an industry-standard tool, thereby addressing one of the main concerns with facilitating wide-spread tool adoption: commercial-level support of deployed products.

REFERENCES

• 1: Elliot J. Chikofsky , James H. Cross II, Reverse Engineering and Design Recovery: A Taxonomy, IEEE Software, v.7 n.1, p.13-17, January 1990 [doi>10.1109/52.43044]
• 2: Jochen Hartmann , Shihong Huang , Scott Tilley, Documenting software systems with views II: an integrated approach based on XML, Proceedings of the 19th annual international conference on Computer documentation, October 21-24, 2001, Sante Fe, New Mexico, USA [doi>10.1145/501516.501571]
• 3: Philippe Kruchten, The Rational Unified Process: an introduction, Addison-Wesley Longman Publishing Co., Inc., Boston, MA, 1999
• 4: Michael Priestley , Mary Hunter Utt, A unified process for software and documentation development, Proceedings of IEEE professional communication society international professional communication conference and Proceedings of the 18th annual ACM international conference on Computer documentation: technology & teamwork, September 24-27, 2000, Cambridge, Massachusetts
• 5: Rational Software Corporation. Rose. Online at www.rational.com/products/rose.
• 6: Rational Software Corporation. Soda. Online at www.rational.com/products/soda.
• 7: The Object Management Group. The Unified Modeling Language. Online at www.omg.org/uml.

INDEX TERMS

Primary Classification:
  D. Software
  D.2 SOFTWARE ENGINEERING
      D.2.7 Distribution, Maintenance, and Enhancement
          Subjects: Documentation

Additional Classification:
  D. Software
  D.2 SOFTWARE ENGINEERING
      D.2.7 Distribution, Maintenance, and Enhancement
          Subjects: Restructuring, reverse engineering, and reengineering

General Terms:
Design, Documentation, Human Factors, Languages

Keywords:
application programming interface (API), automation, documentation, single sourcing, software engineering