CDOC

Test data

The source files shown below were used to create the example output. This program does not do anything useful though it will clean compile. It was written to include language constructs that are commonly found in C programs.

test2.h - the header source

The generated documentation only includes items whose definitions and declarations appear in the header. These are considered to be publicly declared and hence of interest to anybody needing to use code defined in the source file(s) associated with this header. Items declared in the source file(s) are not accessible outside the source file. Hence, these are not of interest and are not documented.

/* TEST2.H - header file for the cdoc utility.
 *           This header should be replaced by
 *           the one in cdoc.c.
 */

#include <stdio.h>
#include "testdummy.h"

#define TRUE      1
#define FALSE     0
#define LBRACKET  "{"
#define RBRACKET  '}'

#define NOVEL     "This is my story"
#define DECISION  { "Yes", "No" }
#define MIN(a,b)  ( a < b ? a )
#define MAX(a,b)  ( a > b ? a )
#define L2C ( x ) ( x & 0xFF )
#undef  L2C
#define ADDRESSOF &x
#define TWOLINES(a,b)  printf("%s\n", a);\
                       printf("%s\n", b)

const char string[] = "My string" ;
const char *mth[] = {"Jan", "Feb", "Mar", "Apr", "May", "Jun",
                     "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"};
enum mth_no         {JAN,   FEB,   MAR,   APR,   MAY,   JUN,
                     JUL,   AUG,   SEP,   OCT,   NOV,   DEC}; 
const char *onoff[] = { "On", "Off" };
const int  switch_state[] = { 1, 0 } ;
const char *decide[] = DECISION;
const int zero = 0;
const int new_value = 1;

enum privacy_values { OFF = 0, ON };
enum{ONE=1,TWO=2};
enum { MAGIC = -7 };
enum { HEX = 1,
       HAX = 2
     };
enum
{
   RED = 0,
   ORANGE = 1,
   YELLOW = 2,
   GREEN,
   BLUE,
   INDIGO,
   VIOLET
}; 
   
typedef int colour_t;
typedef struct {
   int f1;
   char f2;
} my_typedef_struct;


struct my_struct {
   int f3;
   char f4;
};

struct junk{int i; int j;} kipple;
struct complex {double re; double im;};
struct coord{double x; double y;};
struct {int wrongly; int placed;}name;

union u1
{
    int i;
    char c;
};

union u2{char c[4]; float r;};

union u3
{
   my_typedef_struct mts;
   struct junk       cmpl;
};

extern int errno;
static int stasis = 3;
int header_int;
char *global_string = "A sentence in a string";
char *value_3 = "3 = 3";
char *life_cycle[] = { "egg",  "tadpole",
                       "frog", "stork bait" };
                       
/* Function prototypes
   -------------------
*/
int main(int argc, char **argv);
int calculate();
void sentence();
colour_t spectrum(my_typedef_struct a,
                  colour_t def);
struct my_struct *struct_builder(colour_t tint);
old_style(a,b);
void union_diddle(union u2 x);


test2.c - the source file

cdoc starts by reading in the headers that appear as its command line arguments. All C files in the directory are then scanned for #include statements that refer to the header files being processed. These source files are scanned for declarations that match those appearing in the header. Details of these are added to an internal database together with the text in the immediately preceeding comment. If the details of a declaration differ between the header and source file, the source file declaration takes precedence. This allows cdoc to generate the fullest description of the declaration because both K&R and ANSI C function prototypes may contain less detail than the declaration.

/* TEST2.C - The second cdoc test program.
             This program compiles, but many of its declarations
             are meaningless test cases.
*/

#include "test2.h"

/*
   Private constants
*/
const int inner_one = 1;
enum { INNER_TWO = 2 };
#define INNER_THREE 3

/*
   Private function prototypes
*/
void privacy(int in_force);
int  is_private();

/*
   Private global functions
*/
static privacy_state = OFF;

/*
   The program is controlled from here.
   Nothing else much to say, really.
*/
int main(int argc, char **argv)
{
   sentence("This is cdoc talking at yer\n");
   printf("%d = calculate()\n", calculate());
}

/*
   sentence() - A subsidiary function to generate output.
   ==========
*/
void sentence(text)
char *text;
{
   printf(text);   
}

/*
   Check the operation of the MAX macro.
*/
int calculate()
{
   int i = 1,
       j = 10;
       
   return max(i,j);
}

/*
   Example that accepts a typedef and returns another.
*/
colour_t spectrum(my_typedef_struct a,
                  colour_t def)
{
   colour_t x;

   return x;
}

/*
   Another example. This one accepts a typedef
   and returns a struct.
*/
struct my_struct *struct_builder(colour_t tint)
{
   struct my_struct *ss;

   return ss;
}

/*
   A <K&R> definition.
*/
old_style(a,b)
int a;
int b;
{
   return a + b;
}

/*
   Sets the privacy level
*/
void privacy(int in_force)
{
   if (in_force)
      privacy_state = ON;
   else
      privacy_state = OFF;
}

/*
   Test the privacy level
*/
int is_private()
{
   return (privacy_state == ON);
}

/*
   Test the accessibility of union fields
*/
void union_diddle(union u2 x)
{
   x.c[0] = 'a';
   x.c[1] = 'b';
   x.c[2] = 'c';
   x.c[3] = 'd';
   x.r = 1.5e3;
}

/*
   Check union names
*/
void check_unions()
{
   my_typedef_struct m1;
   struct my_struct  m2;
   struct junk       j1;
   struct complex    c1;
   struct coord      c2;
}