Automatic Source Documentation Tool ASCODA for C++

Demonstration

Keywords:

Software Documentation

Groupware

Filters / Converter

Introduction

Problem Description

Software developers (especially in a team) have to share a number of documents:

Architecture and design documents

Development guidelines and standards

Software documentation

Source code

Only very few tools support an integrated access to all of these documents.

During software development, software documentation (code documentation) is often treated as stepchild, especially if the project is subjected to a critical time line. In the first line, it may seem obvious that software documentation is not so important since the code itself can serve as reference. But after a certain time, the amount of code may exceed a size limit where developers can easily find their way through the code of other developers or even their own.

Even if a good software documentation exists, there remains another problem. Since during software development code may change rapidly the documentation is not updated at the same speed and the documentation does not match the current code.

Furthermore common approaches with a separate software documentation lead to a certain amount of redundancy. One has to put comments into the code and write external documents too.

Consequences

Intransparent document structure

High training effort for new team members

Low access speed to documentation

High effort for keeping documentation up to date

Low acceptance of software documentation

Copyright: Danet IS 1995

Automatic Source Code Documentation

Using this approach ASCODA was designed as tool for software documentation. ASCODA is a tool that allows developers to generate software documentation out of source code and to view this documentation in WWW viewers. ASCODA parses the code on access time and creates out of standard headers HTML documents. Any relating document (e.g. architecture or design documents) may be integrated.

Key features are:

Guaranteed up to date documents through on access convertion

Documentation in source code only, low redundancy

Very flexible through use of templates for document format

Can be easily adjusted to standard headers

Direct access to source code out of documentation

Integration with other related documents is easily possible

Overview document: This document is generated out of class

header files and gives a brief description of all classes in a library.

Class description: The class description contains a detailed

documentation of a C++ class, including header path, inheritance and member functions.

Experiences

Right now ASCODA is going to be introduced in a software development project with about 35 developers. A pilot phase has been started.

The use of ASCODA can start step by step. In a software project there are often key parts of code which are shared among a number of developers (e.g. central or basic libraries). Starting with these parts, the benefit of the approach can be visualized. The concept may be applied to other parts of the project later.

Example

Demo of ASCODA