Documentation Comment Extractor

From Ingres Community Wiki

Contents 1 Documentation Comment Extractor 1.1 Usage 1.2 Standard Tools 1.3 Flexible Output Stage 1.4 Template or Boilerplate Production 1.5 Tarball 1.6 Windows Version 1.7 Issues

Documentation Comment Extractor

The Ingres C Coding Standard include guidelines for writing comments that can be used to document the code. The standard used pre-dates most extraction tools and is, as far as I know, not supported by such tools.

Usage

The tool is easy to use:

   cE [-o=<output_file_name>] -f=<output_format> <file_name>

To run the tool on the file ci.c and generate Media Wiki on standard output issue:

   cE -f=MWIKI ci.c

To run the tool on a file and save the output:

   cE -o=ci.mwiki -f=MWIKI ci.c

The result should look like: Ce test ci.c

Available output formats:

 VERIFY:.check comment structure
 MT:.....nroff mt (RTI documentation standard)
 TML:....tWiki
 MWIKI:..Media Wiki

Help is available:

 cE -help

results in:

cE -help
Usage:
   cE [-o=outfile] [-d=1|2|4|16|32] [-f=VERIFY|MT|TML|MWIKI] [-p="preamble"] [-s="postamble"] infile
   Options:
       -o   outfile specifies the output filename.
       -f   VERIFY: check comment structure
            MT:.....nroff mt
            TML:    T Wiki
            MWIKI:..Media Wiki
       -p   "preamble"
       -s   "postamble"
   infile   Input source file

Standard Tools

This tool is written using the standard tools lex and yacc making it easier to maintain and potentially of use for other projects.

Flexible Output Stage

The tool also has a flexible output stage allowing it to be easily adjusted to provide output in pretty much any format.

Template or Boilerplate Production

To make things really easy, the tool can also create a template or boiler plate file.

Tarball

The attached tarball (zip actually, since the wiki doesn't seem to know about .tgz files) contains all you need, including a makefile for Linux. In addition you will need

• A C compiler (e.g. gcc)
• lex
• yacc
• make
• commentExtractor.zip
  • MD5: 73E370CCF55BBD11626E1AFB974A4113 CommentExtractor.zip

Windows Version

Here is a pre-built Windows version (with source) as a single zip:

• CommentExtractor_Windows.zip
  • MD5: A7425BB64AADDC8251C0DF504A1F6E03 CommentExtractor_Windows.zip

Issues

The program makes use of variable length function arguments and this implementation does not seem to work on 64 bit Linux.

The program was developed on Linux and should be easy to port, however I have made no attempt to include platform variants (e.g. there is no Windows specific version of the makefile). An earlier version is known to have run on Solaris.

Not really an issue but... If the source file comments are not well structured then the tool can get somewhat confused resulting in "sub-optimal" output. This is particularly noticeable where the tool tries to guess if a comment contains a list of items. For example, see Ce test ci.c where the first line of each paragraph in the comments is indented, the indentation is preserved faithfully but Media Wiki interprets the leading spaces disrupting the flow of text.