/**
 * 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