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
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:
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.
The DOC_System::process method organizes all objects representing IDL constructs and creates connections between the objects, index, and etc.
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.
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.
(57.3 KB) - added by mgalloy
5 years ago.
IDL coding style guide
(78.9 KB) - added by APanasenco
3 years ago.
Visual representation of the IDLdoc Architecture
(115.9 KB) - added by APanasenco
3 years ago.
Visual description of the parseTree method of the doc_system object
(75.0 KB) - added by APanasenco
3 years ago.
Visual description of the generateOutput method of the doc_system object
(98.1 KB) - added by APanasenco
3 years ago.
Visual description of the process method of the doc_system object