// C documentation generator using markdeep.
// - rlyeh, public domain
//
// build:
// cl docs.c && docs ..\..\v4k.h -x=3rd_glad.h,v4k.h,v4k_main.h,v4k_compat.h, > docs.html
//
// how to document:
// - start documentation on a blank line with a /// 3 slashes comment.
// - all comments must be typed right before the symbol declaration.
// - use `see: symbol1,symbol2^` to create links. `^` char indicates an external link.
// - use `keyword: comment` to create tables. `return:` and `returns` are reserved keywords for function returns.
// - use `> code` to create a snippet. snippets will be multi-lined.
// - use `!!! text` to create a note. severity based on number of exclamations (1:note,2:tip,3:warn,4:alert)
//
// exceptions:
// - a ///- comment can be used to exclude a symbol from any further documentation processing.
// - this ///- comment must be appended to any declaration, at the very end of string.
//
//          #define my_macro() macro_implementation_here() ///-
//
// some examples below:
//
//   /// !!! `filename` must contain extension
//   /// load dynamic library `file` and search for `symbol`
//   /// return: NULL if not found, found symbol otherwise.
//   /// filename: path to dynamic library file. must contain extension.
//   /// symbol: symbol name. must not be NULL.
//   /// see: dlopen^, dlclose^
//   /// > bool (*plugin_init)(void) = dll("plugin.dll", "init");
//   /// > assert(plugin_init());
//   API void* dll(const char *filename, const char *symbol);
//
//   /// split `string` after any of `delimiters` character is found.
//   /// returns temporary array of split strings. see: strjoin
//   /// > array(char*) tokens = strsplit("hello! world!", " !"); // [0]="hello",[1]="world",
//   API array(char*) strsplit(const char *string, const char *delimiters);
//
//   /// concatenate all elements within `list`, with `separator` string in between.
//   /// returns: temporary joint string. see: strsplit
//   /// > array(char*) tokens = strsplit("hello! world!", " !"); // [0]="hello",[1]="world",
//   /// > char *joint = strjoin(tokens, "+"); // joint="hello+world"
//   API char*        strjoin(array(char*) list, const char *separator);
//
//   /// flags when constructing the image_t type. see: image, image_from_mem
//   /// IMAGE_R: 1-channel image (R)
//   /// IMAGE_RG: 2-channel image (R,G)
//   /// IMAGE_RGB: 3-channel image (R,G,B)
//   /// IMAGE_RGBA: 4-channel image (R,G,B,A)
//   /// IMAGE_FLIP: Flip image vertically
//   enum IMAGE_FLAGS {
//       IMAGE_R    = 0x01000,
//       IMAGE_RG   = 0x02000,
//       IMAGE_RGB  = 0x04000,
//       IMAGE_RGBA = 0x08000,
//       IMAGE_FLIP = 0x10000,
//   };
//
//   /// type that holds linear uncompressed bitmap of any given dimensions.
//   /// w,h: image dimensions in pixels. `x,y` alias.
//   /// comps: number of components per pixel. `n` alias.
//   /// pixels: untyped pointer to linear bitmap data. typed pointers use `pixels8/16/32/f` aliases.
//   /// see: texture_t
//   typedef struct image_t {
//       union { unsigned x, w; };
//       union { unsigned y, h; };
//       union { unsigned n, comps; };
//       union { void *pixels; uint8_t *pixels8; uint16_t *pixels16; uint32_t *pixels32; float *pixelsf; };
//   } image_t;

#include "v4k.h"
#include <ctype.h>

int DO_CSS = 1;
int DO_DEBUG = 0;
int DO_README = 1;
int DO_CHANGELOG = 1;

// C preprocessor:
// 1. remove all /* C comments */
// 2. remove all // C++ comments
// 3. remove all \macro continuation lines
// 4. preserve /// comments
void preprocess_c(char *raw) {
    for(int i = 0, in_string = 0; raw[i]; ++i) {
        if( !in_string ) {
            if( raw[i] == '\"' || raw[i] == '\'' ) if( raw[i-1] != '\\' ) {
                in_string = raw[i];
                continue;
            }

            // preserve ///comments
            if( memcmp(&raw[i], "///", 3) == 0 ) {
                while( raw[i] && raw[i] >= 32 ) ++i;
                --i; continue;
            }

            // remove C++ comments
            if( raw[i] == '/' && raw[i+1] == '/' && raw[i+2] != '/' ) {
                do raw[i++] = ' '; while( raw[i] && (raw[i] >= 32 || raw[i] == '\t'));
                --i; continue;
            }

            // remove \macro continuation lines
            if(raw[i] == '\\' && (raw[i+1] && raw[i+1] < 32) && (raw[i+2] && raw[i+2] < 32)) raw[i]=raw[i+1]=raw[i+2] = ' ';
            if(raw[i] == '\\' && (raw[i+1] && raw[i+1] < 32)) raw[i]=raw[i+1] = ' ';

            // remove /* C comments */
            if(raw[i] == '/' && raw[i+1] == '*') {
                raw[i]=raw[i+1]=' ';
                while(raw[i]) if(raw[i] == '*' && raw[i+1] == '/') break; else raw[i++] = ' ';
                if (raw[i]) raw[i] = ' ';
                if (raw[i + 1]) raw[i + 1] = ' ';
                --i; continue;
            }

        } else {
            while(raw[i] == '\\' && raw[i+1]) i += 2;
            if(raw[i] == in_string ) in_string = 0;
            //if(DO_DEBUG) raw[i] = toupper(raw[i]);
        }
    }
    // remove all linefeeds within {} scopes (flatten scopes into single-lines)
    for(int i = 0, open = 0, in_string = 0; raw[i]; ++i) {
        if( !in_string ) {
            if( raw[i] == '\"' || raw[i] == '\'' ) if( raw[i-1] != '\\' ) {
                in_string = raw[i];
                continue;
            }
            // inline brackets. do not process extern "C" { ... } brackets
            if(raw[i] == '{') if(i >= 12 && !memcmp("extern \"C\" {", &raw[i-11], 12) ? 0 : 1) ++open;
            if(raw[i] == '}') if(open > 0) --open;
            if(open > 0) if(raw[i] && raw[i] < 32) raw[i] = ' ';
        } else {
            while(raw[i] == '\\' && raw[i+1]) i += 2;
            if(raw[i] == in_string ) in_string = 0;
        }
    }
}

// Markdown preprocessor:
// 1. replace all {{TEMPLATES}} if defined in OS environment && small enough for inlining
char* preprocess_md(char *raw) {
    for(int i = 0, in_string = 0; raw[i]; ++i) {
        if( !in_string ) {
            if( raw[i] == '\"' /* || raw[i] == '\'' */ ) if( raw[i-1] != '\\' ) {
                in_string = raw[i];
                continue;
            }

            // replace {{TEMPLATE}} symbols if they exist and fit in-place
            if( raw[i] == '{' && raw[i+1] == '{' && raw[i+2] >= 'A') {
                char buf[128];
                if( sscanf(raw+i+2, "%127[^}]", buf) == 1 ) {
                    int buflen = strlen(buf);
                    char *eos = &raw[i+2] + buflen;
                    if( buflen && eos[0] == '}' && eos[1] == '}' ) {
                        char *repl = getenv(buf);
                        if( repl && strlen(repl) <= (buflen + 4) ) {
                            memset(raw+i, ' ', buflen + 4);
                            memcpy(raw+i, repl, strlen(repl));
                            i += buflen+4;
                            --i; continue;
                        }
                    }
                }
            }

        } else {
            while(raw[i] == '\\' && raw[i+1]) i += 2;
            if(raw[i] == in_string ) in_string = 0;
            //if(DO_DEBUG) raw[i] = toupper(raw[i]);
        }
    }
    return raw;
}

// remove whitespaces within a line, unless they are present within a \"string\"
char *minify( const char *line ) {
    // skip initial whitespaces
    line += strspn(line, " \t\r\n");

    // reserve space
    char *bak = strdup/*STRDUP*/(line), *s = bak;

    for(int in_string = 0, seen_alphanum = 0; *line; ++line ) {
        if( !in_string ) {
            // early return till eos if literal /// comment is found.
            if( line[0] == '/' && line[1] == '/' && line[2] == '/' ) {
                strcpy(s, line);
                return bak;
            }
            // detect string open
            if( *line == '\"' || *line == '\'' ) if( line[-1] != '\\' ) {
                in_string = *line;
                *s++ = *line;
                continue;
            }
            // remove spaces
            if( *line > 0 && *line <= 32 ) {
                // keep spacing only if previous char was alphanum && next char is not operator
                const char *next_nbsp = line+1 + strspn(line+1, " \t\r\n");
                #define PUNCT_CHARSET "#" "!&|~" "+-/*%()" "<=>" "[]{}" "?:;" ",'\"\\"
                if(seen_alphanum && !strchr(PUNCT_CHARSET, *next_nbsp)) *s++ = ' ';

                while( *line > 0 && *line <= 32 ) ++line;

                --line;
                continue;
            }
            // save for later
            seen_alphanum = isalnum(*line);
            *s++ = *line;
        } else {
            while(*line == '\\' && line[1]) { memcpy(s, line, 2); s += 2; line += 2; }
            if(*line == in_string ) in_string = 0;

            seen_alphanum = isalnum(*line);
            *s++ = *line;
        }
    }

    *s = 0;
    return bak;
}

bool parse_c_function(const char *raw, int *out_name_pos, int *out_name_len, int *out_args_pos, bool clean_parens) {
    // try to clean up name from worst pathological case with parentheses. ie:
    // API __declspec(dllexport) int(*)(int,...)(MACRO_CALLBACK)(int(*my_callback)(int,...));
    // split declaration into 3 parts: return value, function name, and arguments.
    // 1. string is parsed backwards, from tail to head.
    // 2. arguments are parsed till all matching ( ) chars are balanced.
    // 3. function name is parsed then till '(' or ' ' are found. we remove any parens if present.
    // 4. everything else is the return type.
    bool is_function = false;
    int name = 0, args = 0;
    const char *eos = raw + strlen(raw) - 1;
    for( int i = eos - raw, open = 0; i >= 0; --i ) {
        if( raw[i] == ')' ) ++open;
        if( raw[i] == '(' ) if(open > 0) --open;

        if( raw[i] == '(' && open == 0 ) {
            /**/ if( args == 0 ) args = i;
            else if( name == 0 ) name = i;
        }
        if( (raw[i] == ' ' || raw[i] == '*') && open == 0 && args != 0 && name == 0 ) {
            name = i;
        }

        if( i == 0 ) is_function = (open == 0); // if parens are not balanced, this is not a function
    }
    if( is_function ) {
        // printf("%d %d\n", name, args);
        // printf(">> %.*s\n", args-name, raw+name);
        // printf(">> %s\n", raw + args);
        *out_args_pos = args;
        *out_name_pos = name;
        *out_name_len = args-name;
        if( clean_parens && raw[name] == '(' && raw[args-1] == ')' ) {
            *out_name_pos += 1;
            *out_name_len -= 2;
        }
        return true;
    }
    return false;
}

// reintroduce spacing and tabs where due, so code is pretty much readable again.
// some difficult notes when indenting7cleaning up:
// 1. structs, unions, enums use '{' to increase indenation, and '}' to decrease it.
// 2. structs, unions do line carriage after every member declaration, and keep indentation.
// 3. enums use ',' to linefeed
// 4. we do conversion from static [inline] type func() { ... } -> to -> type func();
// 5. rename functions that are declared between parens to disambiguate macros: int (print)(...);
// 6. do ellipsis on macro contents: #define print(args) ...
char *prettify(char *raw, char **opt_name) {
    if( strbegi(raw, "/""//") ) { raw[0] = 0; return raw; }
    if( strstr(raw, "/""//") ) { *strstr(raw, "/""//") = '\0'; }

    enum { TABS = 4 };

    if(DO_DEBUG) puts(raw);

    static char *buf = 0; buf = REALLOC(buf, strlen(raw) * 16 + 256);
    char *s = buf;

    // hide implementation from static functions
    int is_static = strbegi(raw, "static ");
    int is_static_inline = strbegi(raw, "static inline ");
    if( is_static || is_static_inline ) {
        raw += strlen(is_static_inline ? "static inline " : "static ");
        char *eos = strchr(raw, '{');
        if(eos) eos[0] = ';', eos[1] = 0;
    }

    // hide macro details. expose only name and args
    int is_macro = strbegi(raw, "#define ");
    if( is_macro ) {
        if( raw[8] == '_' && raw[8+1] == '_' ) return raw[0] = 0, raw; // do not process compiler __symbols
        #define KEYWORD_CHARSET "_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
        #define MACRO_CHARSET KEYWORD_CHARSET "$"
        int wordlen = strspn(raw+8, MACRO_CHARSET);
        for( int i = 8 + wordlen, open = 0; raw[i]; ++i ) {
            if( raw[i] == '(' ) { ++open; continue; }
            if( raw[i] == ')' ) { if(open > 0) --open; continue; }
            if( open == 0 ) {
                // hide implementation, until either any of eos or ///comment are found
                while( raw[i] && strcmp(raw+i, "/""//") ) {
                    raw[i++] = ' ';
                }
                break;
            }
        }
        memcpy(raw+=2, "macro", 5); // #define -> macro
    }

    int is_function = raw[0] != '#' && !strchr(raw, '{') && !strchr(raw, '}') && strchr(raw, '(') && strchr(raw, ')') && !strbegi(raw, "typedef");
    if( is_function ) {
        int name = 0, args = 0, namelen = 0;
        is_function = parse_c_function( raw, &name, &namelen, &args, false );
        // clean parens `int (function)(...);` cases
        if( is_function ) { 
            if( raw[name+namelen-1] == ')' ) {
            sprintf(buf, "%.*s%s%.*s%s", name, raw, raw[name-1] == '*' ? "":" ", namelen-2, raw+name+1, raw+args);
            raw = strdup(buf);
            *buf = 0;
            }
        }
    }

    int is_typedef        = strbegi(raw, "typedef "); 
    int is_typedef_enum   = strbegi(raw, "typedef enum");
    int is_typedef_union  = strbegi(raw, "typedef union");
    int is_typedef_struct = strbegi(raw, "typedef struct");
    int is_typedef_block  = is_typedef_enum || is_typedef_union || is_typedef_struct;
    if( is_typedef_block ) {
        raw += strlen("typedef "); // shorten decls on large structs/unions/enums
        char *eos = strrchr(raw, '}');
        if(eos) eos[1] = ';', eos[2] = 0;
    }

    int is_enum = strbegi(raw, "enum");

    const char *remaps[] = { // sort by strlen, then by priority
        "**", "** ",  // char**k
        "(*", " (*",  // int(*fn)();
        "*,", "*, ",  // int printf(char*,...);
        "*)", "*)",   // (char*)k here to fix ')' case below
        "*", "* ",    // char*k
        ",}", "}",    // enum{A,B,}
        ");", ");",   // int func(); here to fix ')' case below
        "};", "}; ",  // struct k{union{int k;};}; here to fix '}' case below
        "}",  "} ",   // typedef struct k{int k;}type;
        "{",  " { ",  // struct k{}
//      ",",  ", ",   // print(int a,int b)
        ";",  "; ",   // struct{int a;int b;};
        "=",  " = ",  // enum{N=1,}
    };
    // 1st pass, spacing
    for( int i = 0; raw[i]; ++i ) {
        *s++ = raw[i];
        for( int j = 0; j < countof(remaps) / 2; ++j ) {
            if(!strncmp(&raw[i], remaps[j*2+0], strlen(remaps[j*2+0]))) {
                --s;
                s += sprintf(s, "%s", remaps[j*2+1]);
                i += strlen(remaps[j*2+0]) - 1;
                break;
            }
        }
        // fix array(char*)strplit(...) or array(int)list(...) case
        // but dont in int(*callback_t)(...) case
        if( i > 0 && s[-1] == ')' && strchr(KEYWORD_CHARSET, raw[i+1]) ) {
            *s++ = ' ';
        }
    }
    if(DO_DEBUG) puts(buf);

    // prepare for 2nd pass
    *s++ = 0;
    raw =  buf + ALLOCSIZE(buf)-1 - strlen(buf)-1;
    strcpy(buf + ALLOCSIZE(buf)-1 - strlen(buf)-1, buf);
    s = buf;

    // 2nd pass, multi-lines
    for(int i = 0, level = 0; raw[i]; ++i) {
        int indent_inc = (raw[i] == '{');
        int indent_dec = (raw[i] == '}');
        int linefeed = indent_inc || indent_dec || (raw[i] == ';') || (is_enum && raw[i] == ',');

        if( !linefeed ) {
            *s++ = raw[i];
        } else {

            if( indent_dec ) {
                if( is_enum ) s += sprintf(s, "\n%*s", (level-1)*TABS, "");
                else          if( level > 0 ) s -= TABS;
            }

            /**/ if( indent_inc ) s += sprintf(s, "%c%s\n%*s", raw[i], raw[i+1] == ';' ? ";" : "", ++level * TABS, "");
            else if( indent_dec ) s += sprintf(s, "%c%s\n%*s", raw[i], raw[i+1] == ';' ? ";" : "", --level * TABS, "");
            else                  s += sprintf(s, "%c%s\n%*s", raw[i], raw[i+1] == ';' ? ";" : "",   level * TABS, "");

            // consume semicolon
            while(raw[i+1] == ';') ++i;
            // consume whitespaces
            while(raw[i+1] == ' ') ++i;
        }
    }
    // if(DO_DEBUG) puts(buf); // no need to debug this one, gonna be printed anyways

    // prepare for last pass
    *s = 0;
    s = buf;
    // last pass: remove extra linefeeds at eos
    while( s[strlen(s)-1] == '\n' ) s[strlen(s)-1] = 0;

    // extract type+name if needed
    if( opt_name ) {
        const char *line = buf;
        bool is_function = strchr(line, '(') && strchr(line, '(') < strrchr(line, ')');

        char s[1024]; int n,nl,a;
        /**/ if( line[0] == '#' )          { sscanf(line, "%*s %s", s);   *opt_name = stringf("#%s",s); }
        else if( strbegi(line, "macro"))   { sscanf(line, "%*s %[^(]",s); *opt_name = stringf("m%s",s); }
        else if( strbegi(line, "union"))   { sscanf(line, "%*s %s",s);    *opt_name = stringf("u%s",s); }
        else if( strbegi(line, "struct"))  { sscanf(line, "%*s %s",s);    *opt_name = stringf("s%s",s); }
        else if( strbegi(line, "enum"))    { sscanf(line, "%*s %s",s);    *opt_name = stringf("e%s",s); }
        else if( strbegi(line, "typedef")) { 
            char *last_word = strrchr(line, ' ') + 1;
            sscanf(last_word, "%[^[;]", s);
            if( strchr(s, ')') ) {
                line += strlen("typedef ");
                parse_c_function(line,&n,&nl,&a,1);
                line += n;
                if(*line == '*') line++, --nl;
                sprintf(s, "%.*s", nl, line);
            }
            *opt_name = stringf("t%s",s);
        }
        else if( line[0] != '#' && is_function && parse_c_function(line,&n,&nl,&a,1)) { 
            while(line[n] == ' ' || line[n] == '*') ++n, --nl; 
            sprintf(s,"%.*s",nl,line+n); 
            *opt_name = stringf("f%s",s);
        }
        // else isvar {}

        // trim whitespaces
        if(*opt_name && strchr(*opt_name, ' ')) {
        *strchr(*opt_name, ' ') = 0;
        }

        // disambiguate macros()<->defines
        if(*opt_name && *opt_name[0] == 'm') {
            #if 1
            char upper[128] = {0}, *u = upper, lower[128] = {0}, *l = lower;
            for( char *p = *opt_name+1; *p; ++p) {
                *u++ = toupper(*p);
                *l++ = tolower(*l);
            }
            if( !strcmp(lower, *opt_name+1) ) *opt_name[0] = 'm';
            if( !strcmp(upper, *opt_name+1) ) *opt_name[0] = 'd';
            #else
            char *found = strstr(line, va("%s(", (*opt_name)+1));
            if(!found)
            *opt_name[0] = 'd';
            #endif
        }
    }

    return buf;
}

int sort_strcmp( const void *str1, const void *str2 ) {
    const char *const *pp1 = str1;
    const char *const *pp2 = str2;
    return strcmpi(*pp1, *pp2);
}

// db cache
array(char*) description;
array(char*) arguments;
array(char*) returns;
array(char*) example;
array(char*) links;
array(char*) notes;

array(char*) defines;
array(char*) enums;
array(char*) types; // unions,structs,typedefs
array(char*) functions;
array(char*) macros;

char *learn(char *line) {
    // @todo: learn markdeep from [line] based on array(context)
    // @todo: update caches & context
    // [...]

    // continue with pretty line
    char* typename = 0;
    char *pretty = prettify(strdup(line), &typename);

if( strbegi(line, "/""//") && line[3] != '/' ) {
    char *md = line + 3 + (line[3] == ' ');

    if( strbegi(md, "returns" ) ) {
        // inline replacement
        memcpy(md, "return:", 7);
    }

    // grab links & truncate line if needed
    if( strstr(md, "see:") ) {
        char *found = strstr(md, "see:");
        array(char*) tokens = strsplit(found+4, " ,.");
        for( int i = 0, end = array_count(tokens); i < end; ++i) {
            array_push(links, tokens[i]);
        }
        *found = '\0';
    }

    if( strbegi(md, "example:") ) {
        array_push(example, va("%s", md+8));
    }
    else if( strbegi(md, "> ") ) {
        array_push(example, va("%s", md+2));
    }
    else if( strbegi(md, "!!!! ") ) {
        array_push(notes, va("%d%s", 4, md+5));
    }
    else if( strbegi(md, "!!! ") ) {
        array_push(notes, va("%d%s", 3, md+4));
    }
    else if( strbegi(md, "!! ") ) {
        array_push(notes, va("%d%s", 2, md+3));
    }
    else if( strbegi(md, "! ") ) {
        array_push(notes, va("%d%s", 1, md+2));
    }
    else if( md[0] ) {
        char heading[512]; sscanf(md, "%s", heading);
        char *text = heading[0] && strendi(heading, ":") ? md+strlen(heading) : 0;
        if( text ) {
            if( strbegi(heading, "return") ) {
                array_push(returns, text);
            } else {
                text[-1] = '\0'; // remove ':'
                array_push(arguments, md); // heading
                array_push(arguments, text);
            }
        } else {
            array_push(description, md);
        }
    }
}
else if( typename ) {
    if( typename[0] == 'd' ) array_push(defines, typename+1);
    if( typename[0] == 't' ) array_push(types/*typedefs*/, typename+1);
    if( typename[0] == 'e' ) array_push(enums, typename+1);
    if( typename[0] == 's' ) array_push(types/*structs*/, typename+1);
    if( typename[0] == 'u' ) array_push(types/*unions*/, typename+1);
    if( typename[0] == 'f' ) array_push(functions, typename+1);
    if( typename[0] == 'm' ) array_push(macros, typename+1);
}

    return line;
}

bool group_together() {
    // find relevant syntax blocks that belong together:
    // - they are a group if lines are sticked together, with no newlines.
    // - they are part of a group if both syntax blocks are sharing keywords on them.
    return true;
}

void print_markdeep(const char *line) { // "/// #hello markdeep"
    const char *text = line + 3 + (line[3] == ' ');
    const char *word = text + strspn(text, " \t");
    if( !word[0] ) return;

    int needs_blank =
        strbegi(word, "---") || strbegi(word, "~~~") || strbegi(word, "```");

    int needs_heading =
        strbegi(word, "# ") || // section
        strbegi(word, "**") || strbegi(word, "* ") || // heading and diagrams
        strbegi(word, "- ") || strbegi(word, "1. ") || // un/ordered lists
        strbegi(word, "---") || strbegi(word, "~~~") || strbegi(word, "```") // linebreaks and snippets
            ? 0 : 1;

    printf("%s%s%s\n", needs_blank ? "\n":"", needs_heading ? "- ":"", text);
}

void print_decl(char *line) { // non-const, since prettify can modify input
    if(strbegi(line, "/""//")) return;

    char *typename;
    char *pretty = prettify(line, &typename);

    char type = typename[0], *name = typename+1;

    char *header = "";
    /**/ if( type == 'd' ) header = "🄳"; //
    else if( type == 't' ) header = "🅃"; // 🅣
    else if( type == 'e' ) header = "🄴"; // 🅔
    else if( type == 'u' ) header = "🅂"; // 🅢
    else if( type == 's' ) header = "🅂"; // 🅢
    else if( type == 'f' ) header = "🄵"; // 🅕Ⓕ
    else if( type == 'm' ) header = "🄼"; // 🅜

    // make pretty->oneliner
    bool truncated = 0;
    char *oneliner = CALLOC(1, strlen(pretty) + 64); strcpy(oneliner, pretty);
    if( strchr(oneliner, '\n') ) { // union,struct,enum
        char *patch = strstr(oneliner, name);
        if( patch ) patch += strlen(name), *patch++ = ';', *patch++ = 0, truncated = 1;
    }
    else // typedef
    if( strbegi(oneliner, "typedef") && strchr(oneliner, '(') ) {
        sprintf(oneliner, "typedef %s;", name); // truncate pointer-to-functions to max
        truncated = 1;
    }
    else // function
    if( strchr(oneliner, '(') ) {
#if 0
        // ret name(args); >> name(args)->ret
        char *name_args = va("%s%s", name,strstr(pretty,name)+strlen(name));
        char *ret = va("%.*s", (int)(strstr(pretty,name)-pretty),pretty);
        sprintf(oneliner, "%.*s; // -> %s", (int)strlen(name_args)-1, name_args, ret);
        truncated = 1;
#elif 0
        // ret name(args); >> name(args)->ret
        char *open = va("%s(", name);
        char *ret = va("%.*s", (int)(strstr(pretty,open)-pretty),pretty);
        char *args = va("%s", strstr(pretty,name)+strlen(name));
//        sprintf(oneliner, "%16s %-16s%s", ret, name, args);  //      API void print44     (mat44 m)
//        sprintf(oneliner, "%-16s %-16s%s", ret, name, args); // API void      print44     (mat44 m)
          sprintf(oneliner, "%-16s %s%s", ret, name, args);
        strrepl(&oneliner, " ", "·"); // windows 0xA0 character nbsp, 0xB7 char middle dot
        truncated = 1;
#endif
    }
    else // macro, define
    {}

    // anchor
    printf("<a name=\"%s\"></a>\n", name);

    // functions
    printf("<details><summary><code lang=C>%s %s</code></summary>\n", header, oneliner);

    if( truncated ) {
        printf("~~~~~~C\n"); // linenumbers\n");
        printf("%s\n", pretty); // header, pretty);
        printf("~~~~~~\n");
    }

    if(1) {
        if( description ) {
            puts("");
            for( int i = 0, end = array_count(description); i < end; ++i) {
                description[i][0] = toupper(description[i][0]);
                printf("%s%s\n", description[i], strendi(description[i], ".") || strendi(description[i], ". ") ? "":".");
            }
        }
        if( arguments || returns ) {
            char *glue = returns ? strjoin(returns, ". ") : "";

            glue[0] = toupper(glue[0]);

            if( !arguments ) {
                printf("\nReturns: %s\n", glue);
            } else {
                const char *head =
                    type == 'e' ? "Enum" :
                    type == 'u' || type == 's' ? "Member" :
                    /*type == 'f' ? */ (glue ? "Return" : "Argument");

                printf("\n\n|%s|%s|\n", head, glue);
                printf("|-----|------|\n");
                for( int i = 0, end = array_count(arguments)/2; i < end; ++i ) {
                    char *arg = arguments[i*2+0]; // arg[0] = toupper(arg[0]);
                    char *nfo = arguments[i*2+1]; nfo[0] = toupper(nfo[0]);
                    printf("|`%s`|%s|\n", arg, nfo);
                }
            }
        }
        if( notes ) {
            for( int i = 0, end = array_count(notes); i < end; ++i) {
                int level = notes[i][0] - '0';
                const char *severity[] = { "Note", "Note", "Tip", "WARNING", "ERROR" }; 
                notes[i][1] = toupper(notes[i][1]);
                if( level < 4 )
                printf("!!! %s\n%4s%s\n", severity[ level ], "", notes[i]+1);
                else
                printf("!!! %s: ALERT\n%4s%s\n", severity[ level ], "", notes[i]+1);
            }
        }
        if( example ) {
            puts("\n~~~~~~C linenumbers");
            printf("/* %s example */\n", name);
            for( int i = 0, end = array_count(example); i < end; ++i) {
                puts(example[i]);
            }
            puts("~~~~~~\n");
        }
        if( links ) {
            printf("\nSee also: ");
            const char *sep = "";
            for( int i = 0, end = array_count(links); i < end; ++i) {
                int slen = strlen(links[i]);
                char is_external = links[i][slen-1] == '^';
                if( is_external ) {
                    printf("%s<a href=\"https://google.com/search?q=%.*s\" target=\"_blank\">%.*s</a>", sep, slen-1, links[i], slen-1, links[i]);
                } else {
                    printf("%s[%s](#%s)", sep, links[i], links[i]);
                }
                sep = ", ";
            }
            puts("");
        }

        if(!(description || example || notes || links || returns || arguments)) {
            puts("\nUnder construction. Yet to be documented.");
            puts("\nOther documentation examples: [dll](#dll), [strsplit](#strsplit), [strjoin](#strjoin), [IMAGE_FLAGS](#IMAGE_FLAGS) or [image_t](#image_t).");
        }

        array_free(description);
        array_free(example);
        array_free(notes);
        array_free(links);
        array_free(returns);
        array_free(arguments);
    }

    printf("\n</details>\n\n");
}

int main(int argc, char **argv) {
    // write header+intro
    DO_CSS = flag("-nocss") ? 0 : optioni("--css", DO_CSS);
    DO_DEBUG = optioni("--debug", DO_DEBUG) | flag("-dbg");
    const char *excludes = option("--excluded-sections,--excluded,-x", "");

    if( DO_CSS ) {
        const char *paths[] = {
            "editor/docs/",
            "art/docs/",
            "tools/docs/",
        };
        char *css = 0, *md = 0;
        for( int i = 0; i < countof(paths); ++i ) {
            char *path_md = va("%sdocs.md", paths[i]);
            char *path_css = va("%sdocs.css", paths[i]);
            if(file_exist(path_md))  md  = file_read(path_md);
            if(file_exist(path_css)) css = file_read(path_css);
        }
        if(!css || !css[0]) exit(-puts("error! cannot find docs.css"));
        if(!md || !md[0]) exit(-puts("error! cannot find docs.md"));
        
        strrepl(&css, "\r\n", "\n");
        strrepl(&md, "\r\n", "\n");
        puts( css );
        puts( preprocess_md(md) );
    }
    if( DO_README ) {
        char *md = file_read("README.md");
        strrepl(&md, "\r\n", "\n");
        // seek to first header
        md = strstr(md, "## ");
        // process headers
        while( md && *md ) {
            char *header = strstr(md, "## ") + 3;
            char *footer = strchr(header, '\n'); if(!footer) footer = header + strlen(header) - 1;
            printf("</details>\n\n<details><summary>%.*s</summary>\n\n", (int)(footer - header), header);
            md = strstr(footer, "## ");
            if( md ) printf("%.*s", (int)(md - footer), footer);
            else printf("%s</details>\n\n", footer);
        }
    }

    // headers are enabled by default. sources do not.
    const char *fname = argc > 1 ? argv[1] : __FILE__;
    int is_header_file = 1; // strstr(".h.H", file_ext(fname)) ? 1 : 0;
    char *section = STRDUP(file_name(fname));

    // read & preprocess C file
    char *raw = file_read(fname);
    preprocess_c(raw);
    // if(DO_DEBUG) fprintf(stderr, "%s\n", raw);

    // split into lines
    array(char*) split = strsplit(raw, "\r\n");
    if(DO_DEBUG) fprintf(stderr, "split %d lines\n", (int)array_count(split));

    // minify every line, then learn & cache
    array(char*) file = 0;
    for(int i = 0; i < array_count(split); ++i) {
        char *line = minify(split[i]);
        if( !line[0] ) continue;

        is_header_file |= (strbegi(line, "#pragma once") || strbegi(line, "#line")); // likely a header file
        if(!is_header_file) continue;

        // handle new heading sections
        if( strbegi(line, "#line") ) {
            char newfile[128];
            if(sscanf(line, "%*s %*d %[^\r\n]", newfile) == 1 ) {
                // remove quotes if present
                char *p = &newfile[ newfile[0] == '\"' ];
                if(strrchr(p, '\"')) *strrchr(p, '\"') = 0;
                // store
                section = STRDUP(p);
            }
        }
        // do not process if section is excluded from processing...
        if( section && excludes[0] ) {
            bool is_in_list = !!strstr(excludes, section);
            bool is_whole_list = !strcmp(excludes, section);
            if( is_whole_list || is_in_list ) {
                continue;
            }
        }
        // ...else, process if needed
        if( section ) {
            // remove extension if present
            char *found = strrchr(section, '.'); if(found) *found = 0;
            // print section in Uppercase form
            char *name = section + (strbegi(section, "v4k_") ? 4 : 0);
            //name[0] = toupper(name[0]);
            printf("## %s\n\n", name);
            // reset
            section = NULL;
        }

        if(strendi(line, "/""//-")) continue; // discard explicitly excluded lines

        learn(line);

        bool is_macro = line[0] == '#';
        bool is_enum = strbegi(line, "enum ") || strbegi(line, "enum{");
        bool is_struct = strbegi(line, "struct ") || strbegi(line, "struct{");
        bool is_union = strbegi(line, "union ") || strbegi(line, "union{");
        bool is_block = is_enum || is_struct || is_union;
        bool is_variable = !!strstr(line, "extern ");
        bool is_function = !is_macro && strchr(line, '(') && strchr(line, '(') < strrchr(line, ')');
        bool is_typedef = !is_block && strbegi(line, "typedef ");

        // @todo: sort out display priorities

        // if(DO_DEBUG) printf("L%d [%s]\n", i, line);

        char *request = strstr(line, "/""//+");
        if( request ) {
            // explicit request
            request[3] = ' '; // hide plus sign
            print_markdeep(request);
            request[0] = 0;
            // ...then print decl
            print_decl(line);
            continue;
        }

        if( is_variable || is_function || is_typedef ) {
            print_decl(line);
            continue;
        }
        if( is_block ) {
            print_decl(line);
            continue;
        }
    }

    puts("\n## 🄳 defines");
    array_sort(defines, sort_strcmp);
    array_unique(defines, sort_strcmp);
    { char *sep = ""; for(int i = 0, end = array_count(defines); i < end; ++i)    printf("%s[%s](#%s)", sep, defines[i], defines[i]), sep = ", "; }

    puts("\n## 🄴 enums");
    array_sort(enums, sort_strcmp);
    array_unique(enums, sort_strcmp);
    { char *sep = ""; for(int i = 0, end = array_count(enums); i < end; ++i)      printf("%s[%s](#%s)", sep, enums[i], enums[i]), sep = ", "; }

    puts("\n## 🅃 types");
    array_sort(types, sort_strcmp);
    array_unique(types, sort_strcmp);
    { char *sep = ""; for(int i = 0, end = array_count(types); i < end; ++i)   printf("%s[%s](#%s)", sep, types[i], types[i]), sep = ", "; }

    puts("\n## 🄵 functions");
    array_sort(functions, sort_strcmp);
    array_unique(functions, sort_strcmp);
    { char *sep = ""; for(int i = 0, end = array_count(functions); i < end; ++i)  printf("%s[%s](#%s)", sep, functions[i], functions[i]), sep = ", "; }

    puts("\n## 🄼 macros");
    array_sort(macros, sort_strcmp);
    array_unique(macros, sort_strcmp);
    { char *sep = ""; for(int i = 0, end = array_count(macros); i < end; ++i)     printf("%s[%s](#%s)", sep, macros[i], macros[i]), sep = ", "; }

    if ( DO_CHANGELOG ) {
        printf("\n## c h a n g e l o g\n\n");
        char *chg = file_read("changelog.txt");
        strrepl(&chg, "\r\n", "\n");
        for each_substring(chg, "\n", it) {
            // printf("<details><summary>%s</summary></details>\n", it);
            printf("* %s\n", it);
        }
    }

    puts("\n<script>");
    puts("\nmarkdeepOptions = {");
    puts("\n    tocStyle:'medium', /* auto,none,short,medium,long */");
    puts("\n    definitionStyle:'auto',  /* auto,short,long */");
    puts("\n    linkAPIDefinitions: true, /* true */");
    puts("\n};");
    puts("\n</script>");
    puts("\n<!-- Markdeep: --><script src=\"https://morgan3d.github.io/markdeep/1.13/markdeep.min.js?\" charset=\"utf-8\"></script>");

    fprintf(stderr, "%s\n", "Ok");
}

// full example below:

#line 1000 "docs.h"

/// # This is a demo
/// Below you can find a diagram that illustrates the whole process.
/// *************************************
/// *                                   *
/// * +----------> [] ----+             *
/// * |                   |             *
/// * +-------------------+             *
/// *                                   *
/// *************************************

/* this is a C comment
*/

#   include\
<stdio.h>
  #  define my_test(...) \
    do_nothing

/// this is my image class
struct my_image_t {
    unsigned int width, height, bpp : 10;
    void *pixels;
    union {
        int dummy;
    };
};

typedef struct my_image_t my_image;

/// this is an enumeration
enum my_enumeration {
    ONE = 1,
    TWO = 2,
    THREE,
    FOUR
};

#define my_macro_exposed1() ///
#define my_macro_exposed2() ///exposed with a comment
#define my_macro_not_exposed() ///-

/// this function acts like printf. `fmt` is a C formatted string.
void function_exposed1(char *fmt, ...);
map(char*,array(int)) (function_exposed2)(
    int line1,
    int line2,
    ...
);

array(char*) function_exposed_3(int line);

extern int version;

///------------------