1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
|
/**
* Doc/testing Utilities
* Help I can't document my documentation tool with my documentation tool.
*
* Basics: All to-be-documented functions must be defined with DOCF/DOCF_END.
* Additionally, one needs to put #ifdef DOCS/else/endif around their code and docs:
*
* DOCF(void, foo, void) {
* #ifdef DOCS
* docs go here
* #else
* code goes here
* #endif
* DOCF_END;
* }
*
* D("...") is used for doc lines, DT("...") for doctest lines.
*
* Internal (static) functions cannot currently be documented, but support for them is planned.
*
* You must also put your main within #ifndef DOCS/#endif, if you don't wish to document it:
*
* #ifndef DOCS
* int main(int argc, char *argv[]) {
* }
* #endif
*
* // or (preferred)
*
* DOCF(int, main, int argc, char *argv[]) {
* #ifdef DOCS
* docs go here
* #else
* code goes here
* #endif
* DOCF_END;
* }
*/
#ifdef DOCTEST
#define DOCS
#endif
#ifdef DOCS
/* docs enabled */
struct docs;
extern void docs_for( struct docs *doc, char *sig, char *name, char *params );
extern void docs_line( struct docs *doc, char *s );
extern void docs_testline( struct docs *doc, int lineno, char *file, char *s);
#define DOCF(sig, name, ...) extern void name##_mkdocs ( struct docs *doc ) { docs_for( doc , #sig , #name , #__VA_ARGS__ ); do
#define DOCF_END }while(0)
#define D(s) docs_line(doc, s)
/* enabled unconditionally as doctests are part of and embedded into docs */
#define DT(s) docs_testline(doc, __LINE__, __FILE__, s)
#else
/* docs not enabled */
#define DOCF(sig, name, ...) sig name ( __VA_ARGS__ )
/* for the sake of semicolon */
#define DOCF_END do{}while(0)
#endif
|
