• CLIST creates action-diagram listings or reformats source code.
• CCALL creates tree-diagrams and cross-reference of caller/called functions.
• CCMT creates comment blocks for each function (identifing calling/called functions and identifiers used).
• CREF creates cross-references of local/global identifiers, C++/Java class-hierarchy tree-diagrams and Inheritence/Containment reports
• CMETRIC calculates code complexity and counts code lines/statements/comments.
• JavTREE is our java based viewer for CCALL function trees and CREF class trees.

Overview of CDOC

CDOC is used by managers and programmers to generate information which is used to modify and maintain 'C' and 'C++' software products. Software development managers and professionals, both administrators and developers, find CDOC a great time saver. For poorly documented code or programs that are delivered with inadequate support documentation, CDOC is the premiere way to reverse engineer the software and keep it alive. CDOC unwinds the tangled web of code that may be inherited or simply under development (with the documentation 'to come later'!).

For example, processing our EXAMPLE program can create a graphical (JavaVM or WebBrowser) function hierarchy-tree:

[backup to Contents]

Benefits

Save hours of documentation time

( CDOC is automated and easy-to-use )

Simplify debugging

( CDOC produces clear and accurate documentation )

Save hours of maintenance

( CDOC will produce up-to-date documentation )

Improve program structure and efficiency

( CDOC simplifies understanding of program structure )

Document 'outside programs' for easier understanding and changes

(independent of compiler, processes K&R and ANSI syntax)

[backup to Contents]

Features

Inputs (Compiler compatibility)

Outputs (ASCII, EPSON/LASERJET, RTF, and HTML)

Version-7 and 8 can also generate HTML reports, with extensive cross-links between the reports, so that you can use your favorite WebBrowser to view the reports and click-and-jump between related information. To see for yourself how this works, please browse through out example v81c.htm reports.

CLIST (tm) shows the control-logic ('flow structure') within each function

• Optionally reformats source programs into standard format:
  • Adjusts leading indentation to reflect actual control-logic nesting level
  • Adjusts in-line spacing into standardized format
  • Splits multi-statement lines, and/or open/close braces, into multiple lines
• Produces 'Action-Diagrams' to outline the control-logic structure:
  • Shows structure (vertical line) outlines of control-logic structures
  • Highlights loops (for/while/loop) and exits (break/continue)
  • Shows preprocessor conditional status using '!' (if false) on each line
• Optionally numbers listings for easier reference
  • Optional line numbers and/or page numbers (user specified page titles).

CCALL (tm) caller/called hierarchy ('flow structure') between functions

• Parses 'C','C++' and 'Java' programs to find all functions (or macro functions)
• Creates graphic 'Tree-Diagrams' to show caller/called function hierarchy (and identifies recursion, including 'A-B-C-A' indirect recursion)
• Produces a Files Table-of-Contents (Functions vs. File name and line)
• Creates caller/called summaries of individual function usage
• Generates detailed cross-references of all function definitions and usages

CCMT (tm) generates/inserts/updates function comment blocks

• Reads in files and finds the beginning of each and every individual function
• Discards any previous caller/called and local/global/param comments
• Generates & inserts new caller/called and local/global/param comments
• Retains any user-generated comments (such as 'purpose, algorithms')
• Proceeds to process next function until all functions/files are processed
• Can extract CCMT and user comments for stand-alone documentation
• Can be re-run weeks or months later to update comments automatically

CMETRIC (tm) calculates path complexity/quality for functions

• Calculates the path/logical 'cyclomatic' (McCabe) complexity
• Counts lines with comments, code, number of statements, and total lines

CREF (tm) shows all local/global/parameter/define identifier references

• Parses 'C', 'C++' and 'Java' programs to find all local/parameter/global/defines
• Creates summary system-level list of all individual identifiers
• Creates function or system-level cross-reference of every identifier usage
• Creates local/global/param summaries for each individual function
• Creates graphic Tree-Diagram of Class-Hierarchy for C++ programs

JavTREE (tm) (FREE with CDOC) Java-based graphic tree viewer

• Displays function caller/called trees graphically (using CCALL output)
• Display C++/Java class hierarchy graphically (using CREF output)
• Version-7 and 8 replaces our previous Windows specific viewer with our new JavTREE Java(tm) Graphic Tree Applet/Application (for Web-based or JVM-based viewing).

CHELP (tm) (CHELPwin, CHELPos2) G.U.I. to setup and run CDOC

• Point-and-click to set all the CDOC controls
• Point-and-click to select the desired reports and run the desired CDOC tool
• Point-and-click to select and view the various outputs

[backup to Contents]

Computer Language Review of CDOC

Vol9 No9, Sep92, Pages 81-84, reviewed by Todd Hoff

"If you want to become a 90s kind of programmer, then you need C-DOC from Software Blacksmiths Inc. C-DOC is a suite of five documentation tools for C and C++ to help professional programmers get in touch with their code, gain global perspective, and look at their code not as a collection of separate, individual functions but as an interdependent whole. C-DOC is comprised of five individual parts: C-CALL, C-CMT, C-REF, C-LIST, and C-METRIC (which calculates the McCabe cyclomatic complexity metric)."
:
"C-DOC's packaging and installation provide a metaphore for the whole system -- functional and solid, without frills. Installation was fast, clean, and easy -- make a target directory, move into it, and invoke the install program that politely asks what components to install."
:
"My build tree has 13 subdirectories with a system of recursive makefiles for building various project versions. Because I use several commercial packages with deep include file nesting and build for several target environments, I felt this would give C-DOC's macro processing abilities a good workout. ... C-DOC also supports metacharacters in filenames, making for painless specification of large groups of source files. I quickly made a configuration file specifying all files in my project and for each major subsystem. I then made a configuration file for each set of options I would use. I used batch files to combine configuration options with the source files I wanted to use. This methodolgy worked well and was very flexible. It took about 14 minutes to finish processing my files."
:
"The main product of C-METRIC is a popular metric called the McCabe cyclomatic complexity metric (doesn't it sound impressive?). In simplest terms, the McCabe metric measures the number of decision points in a module. The idea is that the higher the number of decision points, the higher the chances for a bug."
:
"If you find that you've misplaced a function, try C-CALL's table-of-contents feature. ... Let's say you need more than a table-of-contents. A common situation arises when you need to make a small modification for a customer, and you haven't looked at the code for a while. A simple tree diagram of a program's function call hierarchy could help prevent a lot of fumbling. A host of options gives you good control over the tree's format and how much detail is provided. Recursive functions are highlighted. ... A tree drawn with IBM extended line-drawing graphic characters is also available".
:
"Just as functions get buried in code, identifiers get lost among the files. C-REF offers several levels of cross-referencing detail for local, parameter, global, and define identifiers. Using the various options you can enable C++ keyword processing, class identifier tracking, and production of a C++ class-hierarchy diagram. Although the options are cryptic, one of C-DOC's strengths is its ability to handle CX and C++ source. C-DOC eases the angst of anyone who has tried unraveling the inheritance tree of a complex class library.
:
"C-LIST acts as a pretty printer and also produces control logic diagrams of each function. As a pretty printer, you can control how braces are placed, alignment of identifiers, comment alignment, and many other aspects of source-code aesthetics. As a logic-diagrammer, C-LIST highlights loops, exits, and decision structures."
:
"C-CMT generates or updates function comment-blocks at the start of each C function. Many shops require function headers to include information listing what functions are called, what identifiers are used, and, occasionally, even what functions use the current function. How often have you actually seen the headers filled out? Even if they are filled out, how often are they accurate? Did you ever think all that information should be compiled automagically? If so, C-CMT is your tool. C-CMT even preserves any current function comments you may have."
:
"Software Blacksmiths is not Microsoft. It is a small company dedicated to producing quality software tools.... On the whole, C-DOC has a few rough spots, but it also has a lot to offer. Without a doubt, developers coding in C or C++ should give C-DOC a try."

[backup to Contents]

Free Demo program and Free CDOC Updates

Free CDOC & CDOC Professional v8.1 Updates (for registered owners)

[backup to Contents]

Cost, Capacity, and Requirements

CDOC Professional ($299us) (DOS, Windows, Linux (and OS/2 via webDownload))

CONTENTS:

• CDOC Professional includes all the features of CDOC.
• CDOC Professional also includes a 16-bit Windows3.1 version of CDOCwin and CHELPwin.
• CDOC Professional also includes a 32-bit WindowsNT/95 version of CDOCw32.
• CDOC Professional also includes a 32-bit Linux version of CDOClnx.
• CDOC Professional webDownload of a 32-bit OS/2 version of CDOCos2 and CHELPos2.
• The 32-bit programs CDOCw32 and CDOClnx (also CDOCos2) support long file names.
• CDOC Professional also includes an expanded manual in a 3-ring binder with slip-case.

COST:

• $299us ($495 value).

CAPACITY:

• over 1,000,000 lines of user source code.

REQUIRMENTS:

• IBM Personal Computer (386/486/Pentium PC)
• extended memory, and hard disk-drive
• PC-DOS or MS-DOS (version 3.3 or later), and/or...
• Linux (RedHat 6.1+ or other Intel version), and/or...
• Windows (Windows3.1, or Windows95/98/ME, or WindowsNT/2000).
• Also, OS/2 (version 2.x or Warp) via webDownload of CDOCos2

CDOC Standard ($199us) (DOS, Windows GUI)

CONTENTS:

• CDOC is a single integrated program containing all the capabilities of the 5 component programs (CCALL/CLIST/CREF/CCMT/CMETRIC).
• CDOC Standard includes a DOS based version of the CDOC program.
• CDOC Standard also includes a 32-bit WindowsNT/95 version of CDOC_w32.
• CDOC also includes a native Windows3.1 G.U.I CHELPwin, to setup and run the CDOC program.
• CDOC includes a printed and folded/stapled manual.

COST:

• CDOC $199us ($395 value).
• CCALL/CCMT/CLIST/CREF $69us, CMETRIC $59us.

CAPACITY:

• up to 10,000 lines of user source code.

REQUIRMENTS:

[backup to Contents]

Ordering information

The CDOC products may also be ordered from most of the larger software mail-order companies. Their prices and terms vary. For example, you can contact:

• PROVANTAGE 1-800-336-1166.
• Programmers Paradise (Voyageur) 1-800-445-7899
• The SuperShops (Programmers Shop) 1-800-421-8006.

[backup to Contents]

Questions/Comments via EMail or Phone

If you have any questions, please send us an EMail note with the question (try to be as specific as possible so we can ensure a quality reply). If you wish us to call you, enclose your Name and Phone Number in your note and request a follow-up call, or you can give us a call at (905)-858-4466.

[backup to Contents] [next document CLIST]

Author: