doc/api/api.txt

   1 This directory is intended for documents describing programming
   2 interfaces within ircu, including such things as modebuf's and the
   3 features interface.  Please write these documents as plain text; if we
   4 want HTML, we can write a script to convert the text versions into
   5 HTML versions.  Toward that end, I respectfully suggest everyone
   6 conform to a common format, which I will describe here:
   7
   8 Every .txt file should begin with a couple of paragraphs giving an
   9 overview of the API, its purpose, and how to use it.  Paragraphs
  10 should be separated by blank lines, as shown here.  Paragraphs that do
  11 not end in some form of punctuation, such as a period, will be treated
  12 as section headings.  The introduction ends when the first API element
  13 appears.  API element documentation is introduced with "<" followed by
  14 the element type--"struct", "typedef", "function", "macro", or (heaven
  15 forbid) "global", followed by ">", all on a line by itself.  The next
  16 line should contain a declaration of the element as it would appear in
  17 a header file; this may spread across multiple lines and contain
  18 comments and blank lines.  The declaration ends for most elements when
  19 a ";" is encountered; for macros, the declaration ends on the last
  20 line not ending in "\".
  21
  22 The documentation for the API element should immediately follow the
  23 declaration of that element, and should be separated from it by a
  24 single blank line.  This documentation should explain the purpose of
  25 the element and describe what each of its fields mean.  The
  26 documentation ends when the corresponding "</" tag is reached, just as
  27 in HTML or XML.  (I don't intend for the files to be either HTML or
  28 XML, I just want them to be easy to parse so they could be turned into
  29 either, as occasion warrants.)  An example follows:
  30
  31 <struct>
  32 struct FooBar;  /* a sample structure with no definition */
  33
  34 The comment, since it's on the same line as the ";", is associated
  35 with the declaration for struct FooBar.
  36 </struct>
  37
  38 <struct>
  39 struct FooBar {
  40   long     fb_magic;    /* a magic number */
  41   char    *fb_string;   /* a string of some sort */
  42 };
  43
  44 The sequence "};" ends the struct declaration.
  45 </struct>
  46
  47 <typedef>
  48 typedef FooBar_t;       /* a simple typedef */
  49
  50 This element shows how to hide the inner workings of typedefs.
  51 </typedef>
  52
  53 <typedef>
  54 typedef struct FooBar FooBar_t; /* a more complex typedef */
  55
  56 Here we show the full typedef declaration.
  57 </typedef>
  58
  59 <global>
  60 extern int fooBarFreeList;      /* global variables should be avoided */
  61
  62 You should avoid global variables, but if you must have one for alloc
  63 counts or whatever, here's how to specify documentation for them.
  64 </global>
  65
  66 <macro>
  67 #define HAVE_FOOBAR             /* We have FOOBAR, whatever it may be */
  68
  69 This could be used for boolean macros (macros used in #ifdef's, for
  70 instance) or for simple value macros where you're hiding the values.
  71 Since there are so many variations on macros, I'll only show one other
  72 variation below:
  73 </macro>
  74
  75 <macro>
  76 #define FooBarVerify(foobar)    ((foobar) && \
  77                                  (foobar)->fb_magic == FOOBAR_STRUCT_MAGIC)
  78
  79 This macro takes arguments.  Again, we could leave out the actual
  80 definition, or even treat the macro as a function rather than a
  81 macro.  This also shows how to do multi-line macros.
  82 </macro>
  83
  84 <function>
  85 void *foobar(struct FooBar *blah, int flag);
  86
  87 Since function definitions never appear in header files anyway, we
  88 don't have to worry about hiding information.  You should leave off
  89 "extern" in the function declaration, and please include names for the
  90 variables, so you can refer to them in the function documentation.
  91 </function>
  92
  93 The API document may then end in some summary information, if you
  94 wish, or a ChangeLog of some form, such as follows.
  95
  96 <authors>
  97 Kev <klmitch@mit.edu>
  98 </authors>
  99
 100 <changelog>
 101 [2000-12-18 Kev] Initial definition of how API documents should look.
 102 Further entries in the changelog should *precede* this one and should
 103 be separated from it by a blank line.  Also specify your name, as
 104 listed in the "<authors>" section, so we know who to blame ;)
 105 </changelog>