Developer Information

This info page contains all necessary information about developing IDLdoc and should help you ease into the development process.

Table of Contents:

• Goals of IDLdoc
• Architecture and Design
• Development Guidelines
• Submitting Your Work

---

Goals of IDLdoc

IDLdoc is a utility for generating documentation from IDL source code.

IDLdoc aims to:

• Keep source code and its documentation as close as possible to avoid issues where documentation lags behind the implementation.
• Give users of a programming library a quick and intuitive way to find a desired program.
• Provide maximum useful information about each program.
• Create easy-to-follow code documenting standards.
• Provide ways to analyze source code to provide warnings and metrics for documentation completeness, complexity, and other important aspects.

Architecture and Design

This file contains the architecture and directory information for the IDLdoc project.

The below description is a work in progress. Information in it may not necessarily be accurate or complete.

Quick Overview of an IDLdoc run:

1. parseTree

The DOC_System::parseTree method uses the appropriate classes in the parser directory to parse source files and the comments contained in them to create a tree of objects, found in the tree directory, representing IDL constructs.

2. process

The DOC_System::process method organizes all objects representing IDL constructs and creates connections between the objects, index, and etc.

3. generateOutput

The DOC_System::generateOutput method uses the appropriate templates in the templates directory to produce the output. See Report generation using templates for more information on templates.

Development Guidelines

Developers are encouraged to maintain style consistency across the project. A consistent coding style allows for easier reading and comprehension of a large set of programs. The coding conventions used in the IDLdoc project can be found in this Style Guide by Mike Galloy: IDL Style Guide.

The practices in the Style Guide are based primarily on those of higher-level languages. Their goal is to improve the logical structure and readability of your code. Switching from the standard IDL coding style can be hard, however, so just try to focus on a few new practices at a time while writing a new program. If you would like to learn more about the programming practices discussed in the Style Guide, you should get a copy of Code Complete 2 by Steve McConnell.

Submitting Your Work

You can submit your work in the exact same place where you download the source code - in the Browse Source subsection.

The IDLdoc project is hosted on a Subversion version control system. It allows for multiple users to submit their work on a software project online, make revisions and restore previous version of the project. It also allows for easy peer reviews of code.

Most of the time when you will submit a change to IDLdoc, you will submit it on /trunk. This subdirectory holds the source code for the latest stable version of the program. Keep in mind that /trunk must compile and pass regression tests at all times. This policy is strictly enforced and commiters who violate it will be publicly humiliated.

A single commit (changeset) must not be so large so as to discourage peer review of the changes. If it's impossible to make a series of small changes without disrupting the stability of /trunk, then the user should create a branch and submit a series of smaller changes there. This allows for peer review without compromising the stable source code. Also, please branch when you are merely experimenting with the code or are making changes that the other developers do not necessarily agree with.

Check out this Visual Guide to better understand the concepts and terms of version control.