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.
- Chikofsky, E.; and Cross, J. "Reverse Engineering and Design Recovery: A Taxonomy." IEEE Software 7(1):13-17, January 1990. Google ScholarDigital Library
- Hartmann, J.; Huang, S.; and Tilley, S. "Documenting Software Systems with Views II: An Integrated Approach Based on XML." Proceedings of the 19th Annual International Conference on Systems Documentation (SIGDOC 2001: Santa Fe, NM; October 21-24, 2001), pp. 237-246. ACM Press: New York, NY, 2001. Google ScholarDigital Library
- Kruchten, P. The Rational Unified Process (2nd edition). Addison-Wesley, 2000. Google ScholarDigital Library
- Priestly, M.; and Utt, M. "A Unified Process for Software and Documentation Development." Proceedings of the 18th Annual International Conference on Systems Documentation (SIGDOC 2000: Boston, MA; September 24-27, 2001), pp. 221--238. IEEE: Piscataway, NJ, 2000. Google ScholarDigital Library
- Rational Software Corporation. Rose. Online at www.rational.com/products/rose.Google Scholar
- Rational Software Corporation. Soda. Online at www.rational.com/products/soda.Google Scholar
- The Object Management Group. The Unified Modeling Language. Online at www.omg.org/uml.Google Scholar
Index Terms
- Automatically connecting documentation to code with rose
Recommendations
Documentation for software engineers: what is needed to aid system understanding?
SIGDOC '01: Proceedings of the 19th annual international conference on Computer documentationSoftware engineers rely on program documentation as an aid in understanding the functional nature, high-level design, and implementation details of complex applications. However, no one really knows what types of documentation are truly useful to ...
Automated example oriented REST API documentation at Cisco
ICSE-SEIP '17: Proceedings of the 39th International Conference on Software Engineering: Software Engineering in Practice TrackGenerating and maintaining an up-to-date API documentation is a challenging problem for evolving REST APIs. At Cisco, we've used SpyREST, an automated REST API documentation tool, via our functional tests to solve this problem with one of our APIs for a ...
SpyREST in action: an automated RESTful API documentation tool
ASE '15: Proceedings of the 30th IEEE/ACM International Conference on Automated Software EngineeringRESTful APIs are often manually documented. As a result, the process of maintaining the documentation of RESTful APIs is both expensive and error-prone. In this demonstration paper, we present SpyREST as an automated software as a service tool that can ...
Comments