diff options
Diffstat (limited to 'src/doctest.h')
-rw-r--r-- | src/doctest.h | 66 |
1 files changed, 66 insertions, 0 deletions
diff --git a/src/doctest.h b/src/doctest.h new file mode 100644 index 0000000..7c5403b --- /dev/null +++ b/src/doctest.h @@ -0,0 +1,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 |