]>
Commit | Line | Data |
---|---|---|
189935b1 | 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> |