tools/cxref/README.c

   1 /*****************
   2   $Header$
   3
   4   A comment for the file, RCS header comments are treated specially when first.
   5   *****************/
   6
   7
   8
   9 /*+ A #include comment +*/
  10 #include <stdio.h>
  11
  12
  13 #include <math.h>  /*+ An alternative #include comment. +*/
  14
  15
  16 /*+ A #define comment. +*/
  17 #define def1 1
  18
  19
  20 #define def2 2  /*+ An alternative #define comment. +*/
  21
  22
  23 /*+++++++++++
  24   A #define with args
  25
  26   arg1 The first arg
  27
  28   arg2 The second arg
  29   +++++++++++*/
  30
  31 #define def3(arg1,arg2) (arg1+arg2)
  32
  33
  34 /*+ An alternative #define with args. +*/
  35
  36 #define def4(arg1 /*+ The first arg  +*/, \
  37              arg2 /*+ The second arg +*/) \
  38            (arg1+arg2)
  39
  40
  41 /*+ An example typedef comment +*/
  42 typedef enum
  43 {
  44  one,            /*+ one value +*/
  45  two             /*+ another value +*/
  46 }
  47 type1;
  48
  49
  50 /*+ Another example typedef comment, +*/
  51 typedef struct
  52 {
  53  int a;         /*+ A variable in a struct. +*/
  54  union bar
  55   {
  56    char a;      /*+ Each element +*/
  57    int  b,      /*+ of a struct +*/
  58         c;      /*+ or a union +*/
  59    long d;      /*+ can have a comment +*/
  60   }
  61  e;             /*+ Nested structs and unions also work. +*/
  62 }
  63 type2,          /*+ a type that is a struct. +*/
  64 *ptype2;        /*+ a pointer to a struct type. +*/
  65
  66
  67 /*+ A leading comment only. +*/
  68 int var1,var2;
  69
  70
  71 static int var3; /*+ A trailing comment only. +*/
  72
  73
  74 /*+ A variable for +*/
  75 int var4,    /*+ one thing. +*/
  76     var5,    /*+ a second thing. +*/
  77     var6;    /*+ a third thing. +*/
  78
  79 /* Note: The leading comment is combined with each of the trailing comments. */
  80 /* Note: the push through of the comment above on the ',' and ';', see README. */
  81
  82
  83 /*+++++++++++
  84   A function comment (the comments for the args need to be separated by a blank line).
  85
  86   int function1 The return value.
  87
  88   int arg1 The first argument.
  89
  90   int arg2 The second argument.
  91
  92   Some more comments
  93
  94   +none+  Note: this line and the two below are processed specially.
  95   +html+  This comment is only visible in the HTML output, and can contain HTML markup.
  96   +latex+ This comment is only visible in the \LaTeX output, and can contain \LaTeX markup.
  97   +++++++++++*/
  98
  99 int function1(int arg1,int arg2)
 100 {
 101  /*+ An internal comment in a function that appears as a
 102    new paragraph at the end of the comment. +*/
 103
 104  var1=0;
 105
 106  function2(var3,var4);
 107 }
 108
 109
 110 /*+ An alternative function comment +*/
 111
 112 int function2(int arg1,  /*+ The first argument.  +*/
 113               int arg2)  /*+ The second argument. +*/
 114 /*+ Returns a value +*/
 115 {
 116  int (*funcp)()=&function1;
 117 }
 118
 119 /* Note: the push through of the comment above on the ',' and ')', see README. */