ircu api - api

This directory is intended for documents describing programming interfaces within ircu, including such things as modebuf's and the features interface. Please write these documents as plain text; if we want HTML, we can write a script to convert the text versions into HTML versions. Toward that end, I respectfully suggest everyone conform to a common format, which I will describe here:

Every .txt file should begin with a couple of paragraphs giving an overview of the API, its purpose, and how to use it. Paragraphs should be separated by blank lines, as shown here. Paragraphs that do not end in some form of punctuation, such as a period, will be treated as section headings. The introduction ends when the first API element appears. API element documentation is introduced with "<" followed by the element type--"struct", "typedef", "function", "macro", or (heaven forbid) "global", followed by ">", all on a line by itself. The next line should contain a declaration of the element as it would appear in a header file; this may spread across multiple lines and contain comments and blank lines. The declaration ends for most elements when a ";" is encountered; for macros, the declaration ends on the last line not ending in "\".

The documentation for the API element should immediately follow the declaration of that element, and should be separated from it by a single blank line. This documentation should explain the purpose of the element and describe what each of its fields mean. The documentation ends when the corresponding "</" tag is reached, just as in HTML or XML. (I don't intend for the files to be either HTML or XML, I just want them to be easy to parse so they could be turned into either, as occasion warrants.) An example follows:

struct FooBar;	/* a sample structure with no definition */

The comment, since it's on the same line as the ";", is associated with the declaration for struct FooBar.

struct FooBar { long    fb_magic;	/* a magic number */ char   *fb_string;	/* a string of some sort */ };

The sequence "};" ends the struct declaration.

typedef FooBar_t;	/* a simple typedef */

This element shows how to hide the inner workings of typedefs.

typedef struct FooBar FooBar_t;	/* a more complex typedef */

Here we show the full typedef declaration.

extern int fooBarFreeList;	/* global variables should be avoided */

You should avoid global variables, but if you must have one for alloc counts or whatever, here's how to specify documentation for them.


 * 1) define HAVE_FOOBAR		/* We have FOOBAR, whatever it may be */

This could be used for boolean macros (macros used in #ifdef's, for instance) or for simple value macros where you're hiding the values. Since there are so many variations on macros, I'll only show one other variation below:

(foobar)->fb_magic == FOOBAR_STRUCT_MAGIC)
 * 1) define FooBarVerify(foobar)	((foobar) && \

This macro takes arguments. Again, we could leave out the actual definition, or even treat the macro as a function rather than a macro. This also shows how to do multi-line macros.

void *foobar(struct FooBar *blah, int flag);

Since function definitions never appear in header files anyway, we don't have to worry about hiding information. You should leave off "extern" in the function declaration, and please include names for the variables, so you can refer to them in the function documentation.

The API document may then end in some summary information, if you wish, or a ChangeLog of some form, such as follows.

Kev 

[2000-12-18 Kev] Initial definition of how API documents should look. Further entries in the changelog should *precede* this one and should be separated from it by a blank line. Also specify your name, as listed in the " " section, so we know who to blame ;)