sqlite3: add schema comments

Comments should help DB users that are unfamiliar to doxygen internals.

You can dump the schema with:

   echo ".schema" | sqlite3 doxygen_sqlite3.db

1 files changed, 127 insertions, 107 deletions

diff --git a/src/sqlite3gen.cpp b/src/sqlite3gen.cpp
index 580042f..ba72b55 100644
--- a/src/sqlite3gen.cpp
+++ b/src/sqlite3gen.cpp
@@ -47,134 +47,154 @@
 
 const char * schema_queries[][2] = {
   { "includes",
-    "CREATE TABLE IF NOT EXISTS includes ("
-      "rowid INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, "
-      "local INTEGER NOT NULL,"
-      "id_src INTEGER NOT NULL,"
-      "id_dst INTEGER NOT NULL);"
-    "CREATE UNIQUE INDEX idx_includes ON includes "
-      "(local, id_src, id_dst);"
+    "CREATE TABLE IF NOT EXISTS includes (\n"
+      "\t-- #include relations.\n"
+      "\trowid        INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,\n"
+      "\tlocal        INTEGER NOT NULL,\n"
+      "\tid_src       INTEGER NOT NULL,  -- File id of the includer.\n"
+      "\tid_dst       INTEGER NOT NULL   -- File id of the includee.\n"
+      ");\n"
+    "CREATE UNIQUE INDEX idx_includes ON includes\n"
+      "\t(local, id_src, id_dst);"
   },
   { "innerclass",
-    "CREATE TABLE IF NOT EXISTS innerclass ("
-      "rowid INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, "
-      "refid TEXT NOT NULL,"
-      "prot INTEGER NOT NULL,"
-      "name TEXT NOT NULL)"
+    "CREATE TABLE IF NOT EXISTS innerclass (\n"
+      "\trowid        INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,\n"
+      "\trefid        TEXT NOT NULL,\n"
+      "\tprot         INTEGER NOT NULL,\n"
+      "\tname         TEXT NOT NULL\n"
+      ");"
   },
   { "files",
-    "CREATE TABLE IF NOT EXISTS files ("
-      "name TEXT PRIMARY KEY NOT NULL);"
+    "CREATE TABLE IF NOT EXISTS files (\n"
+      "\t-- Names of source files and includes.\n"
+      "\tname         TEXT PRIMARY KEY NOT NULL\n"
+      ");"
   },
   { "refids",
-    "CREATE TABLE IF NOT EXISTS refids ("
-      "refid TEXT PRIMARY KEY NOT NULL);"
+    "CREATE TABLE IF NOT EXISTS refids (\n"
+      "\trefid        TEXT PRIMARY KEY NOT NULL\n"
+      ");"
   },
   { "xrefs",
-    "CREATE TABLE IF NOT EXISTS xrefs ("
-      "rowid INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,"
-      "refid_src INTEGER NOT NULL, "
-      "refid_dst INTEGER NOT NULL, "
-      "id_file INTEGER NOT NULL, "
-      "line INTEGER NOT NULL, "
-      "column INTEGER NOT NULL);"
-    "CREATE UNIQUE INDEX idx_xrefs ON xrefs "
-      "(refid_src, refid_dst, id_file, line, column);"
+    "CREATE TABLE IF NOT EXISTS xrefs (\n"
+      "\t-- Cross reference relation.\n"
+      "\trowid        INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,\n"
+      "\trefid_src    INTEGER NOT NULL, -- referrer id.\n"
+      "\trefid_dst    INTEGER NOT NULL, -- referee id.\n"
+      "\tid_file      INTEGER NOT NULL, -- file where the reference is happening.\n"
+      "\tline         INTEGER NOT NULL, -- line where the reference is happening.\n"
+      "\tcolumn       INTEGER NOT NULL  -- column where the reference is happening.\n"
+      ");\n"
+    "CREATE UNIQUE INDEX idx_xrefs ON xrefs\n"
+      "\t(refid_src, refid_dst, id_file, line, column);"
   },
   { "memberdef",
-    "CREATE TABLE IF NOT EXISTS memberdef ("
-      "rowid INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, "
-      "id_file INTEGER NOT NULL,"
-      "line INTEGER NOT NULL,"
-      "column INTEGER NOT NULL,"
-      "refid TEXT NOT NULL,"
-      "name TEXT NOT NULL,"
-      "definition TEXT,"
-      "type TEXT,"
-      "argsstring TEXT,"
-      "scope TEXT,"
-      "initializer TEXT,"
-      "prot INTEGER,"
-      "const INTEGER,"
-      "virt INTEGER,"
-      "static INTEGER NOT NULL,"
-      "explicit INTEGER,"
-      "inline INTEGER,"
-      "final INTEGER,"
-      "sealed INTEGER,"
-      "new INTEGER,"
-      "optional INTEGER,"
-      "required INTEGER,"
-      "mutable INTEGER,"
-      "initonly INTEGER,"
-      "readable INTEGER,"
-      "writable INTEGER,"
-      "gettable INTEGER,"
-      "settable INTEGER,"
-      "accessor INTEGER,"
-      "addable INTEGER,"
-      "removable INTEGER,"
-      "raisable INTEGER,"
-      "kind INTEGER,"
-      "id_bodyfile INTEGER,"
-      "bodystart INTEGER,"
-      "bodyend INTEGER,"
-      "detaileddescription TEXT,"
-      "briefdescription TEXT,"
-      "inbodydescription TEXT"
-      ")"
+    "CREATE TABLE IF NOT EXISTS memberdef (\n"
+      "\t-- All processed identifiers.\n"
+      "\trowid        INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,\n"
+      "\tid_file      INTEGER NOT NULL,  -- file where this identifier is located\n"
+      "\tline         INTEGER NOT NULL,  -- line where this identifier is located\n"
+      "\tcolumn       INTEGER NOT NULL,  -- column where this identifier is located\n"
+      "\trefid        TEXT NOT NULL,     -- see the refids table\n"
+      "\tname         TEXT NOT NULL,\n"
+      "\tdefinition   TEXT,\n"
+      "\ttype         TEXT,\n"
+      "\targsstring   TEXT,\n"
+      "\tscope        TEXT,\n"
+      "\tinitializer  TEXT,\n"
+      "\tprot         INTEGER DEFAULT 0, -- 0:public 1:protected 2:private 3:package\n"
+      "\tconst        INTEGER DEFAULT 0, -- 0:non-constant 1:constant\n"
+      "\tvirt         INTEGER DEFAULT 0, -- 0:non-virtual 1:virtual 2:pure-virtual\n"
+      "\tstatic       INTEGER DEFAULT 0, -- 0:non-static 1:static\n"
+      "\texplicit     INTEGER DEFAULT 0,\n"
+      "\tinline       INTEGER DEFAULT 0,\n"
+      "\tfinal        INTEGER DEFAULT 0,\n"
+      "\tsealed       INTEGER DEFAULT 0,\n"
+      "\tnew          INTEGER DEFAULT 0,\n"
+      "\toptional     INTEGER DEFAULT 0,\n"
+      "\trequired     INTEGER DEFAULT 0,\n"
+      "\tmutable      INTEGER DEFAULT 0,\n"
+      "\tinitonly     INTEGER DEFAULT 0,\n"
+      "\treadable     INTEGER DEFAULT 0,\n"
+      "\twritable     INTEGER DEFAULT 0,\n"
+      "\tgettable     INTEGER DEFAULT 0,\n"
+      "\tsettable     INTEGER DEFAULT 0,\n"
+      "\taccessor     INTEGER DEFAULT 0,\n"
+      "\taddable      INTEGER DEFAULT 0,\n"
+      "\tremovable    INTEGER DEFAULT 0,\n"
+      "\traisable     INTEGER DEFAULT 0,\n"
+      /// @todo make a `kind' table
+      "\tkind         INTEGER DEFAULT 0, -- 0:define 1:function 2:variable 3:typedef 4:enum 5:enumvalue 6:signal 7:slot 8:friend 9:DCOP 10:property 11:event\n"
+      "\tid_bodyfile  INTEGER DEFAULT 0, -- file of definition\n"
+      "\tbodystart    INTEGER DEFAULT 0, -- starting line of definition\n"
+      "\tbodyend      INTEGER DEFAULT 0, -- ending line of definition\n"
+      /// @todo make a `detaileddescription' table
+      "\tdetaileddescription  TEXT,\n"
+      "\tbriefdescription     TEXT,\n"
+      "\tinbodydescription    TEXTi\n"
+      ");"
   },
   { "compounddef",
-    "CREATE TABLE IF NOT EXISTS compounddef ("
-      "rowid INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,"
-      "name TEXT NOT NULL,"
-      "kind TEXT NOT NULL,"
-      "prot INTEGER NOT NULL,"
-      "refid TEXT NOT NULL,"
-      "id_file INTEGER NOT NULL,"
-      "line INTEGER NOT NULL,"
-      "column INTEGER NOT NULL)"
+    "CREATE TABLE IF NOT EXISTS compounddef (\n"
+      "\t-- class/struct definitions.\n"
+      "\trowid        INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,\n"
+      "\tname         TEXT NOT NULL,\n"
+      "\tkind         TEXT NOT NULL,\n"
+      "\trefid        TEXT NOT NULL,\n"
+      "\tprot         INTEGER NOT NULL,\n"
+      "\tid_file      INTEGER NOT NULL,\n"
+      "\tline         INTEGER NOT NULL,\n"
+      "\tcolumn       INTEGER NOT NULL\n"
+      ");"
   },
   { "basecompoundref",
-    "CREATE TABLE IF NOT EXISTS basecompoundref ("
-      "rowid INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, "
-      "base TEXT NOT NULL,"
-      "derived TEXT NOT NULL,"
-      "refid TEXT NOT NULL,"
-      "prot INTEGER NOT NULL,"
-      "virt INTEGER NOT NULL)"
+    "CREATE TABLE IF NOT EXISTS basecompoundref (\n"
+      "\trowid        INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,\n"
+      "\tbase         TEXT NOT NULL,\n"
+      "\tderived      TEXT NOT NULL,\n"
+      "\trefid        TEXT NOT NULL,\n"
+      "\tprot         INTEGER NOT NULL,\n"
+      "\tvirt         INTEGER NOT NULL\n"
+      ");"
   },
   { "derivedcompoundref",
-    "CREATE TABLE IF NOT EXISTS derivedcompoundref ("
-      "rowid INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, "
-      "base TEXT NOT NULL,"
-      "derived TEXT NOT NULL,"
-      "refid TEXT NOT NULL,"
-      "prot INTEGER NOT NULL,"
-      "virt INTEGER NOT NULL)"
+    "CREATE TABLE IF NOT EXISTS derivedcompoundref (\n"
+      "\trowid        INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,\n"
+      "\tbase         TEXT NOT NULL,\n"
+      "\tderived      TEXT NOT NULL,\n"
+      "\trefid        TEXT NOT NULL,\n"
+      "\tprot         INTEGER NOT NULL,\n"
+      "\tvirt         INTEGER NOT NULL\n"
+      ");"
   },
   { "params",
-    "CREATE TABLE IF NOT EXISTS params ("
-      "rowid INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,"
-      "attributes TEXT,"
-      "type TEXT,"
-      "declname TEXT,"
-      "defnname TEXT,"
-      "array TEXT,"
-      "defval TEXT,"
-      "briefdescription TEXT)"
+    "CREATE TABLE IF NOT EXISTS params (\n"
+      "\t-- All processed parameters.\n"
+      "\trowid        INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,\n"
+      "\tattributes   TEXT,\n"
+      "\ttype         TEXT,\n"
+      "\tdeclname     TEXT,\n"
+      "\tdefnname     TEXT,\n"
+      "\tarray        TEXT,\n"
+      "\tdefval       TEXT,\n"
+      "\tbriefdescription TEXT\n"
+      ");"
   },
   { "memberdef_params",
-    "CREATE TABLE IF NOT EXISTS memberdef_params ("
-      "rowid INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,"
-      "id_memberdef INTEGER NOT NULL,"
-      "id_param INTEGER NOT NULL)"
+    "CREATE TABLE IF NOT EXISTS memberdef_params (\n"
+      "\t-- Junction table for memberdef parameters.\n"
+      "\trowid        INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,\n"
+      "\tid_memberdef INTEGER NOT NULL,\n"
+      "\tid_param     INTEGER NOT NULL\n"
+      ");"
   },
   { "innernamespaces",
-    "CREATE TABLE IF NOT EXISTS innernamespaces ("
-      "rowid INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,"
-      "refid TEXT NOT NULL,"
-      "name TEXT NOT NULL)"
+    "CREATE TABLE IF NOT EXISTS innernamespaces (\n"
+      "\trowid        INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,\n"
+      "\trefid        TEXT NOT NULL,\n"
+      "\tname         TEXT NOT NULL\n"
+      ");"
   }
 };
 
@@ -407,7 +427,7 @@ static void insertMemberReference(sqlite3 *db, MemberDef *src, MemberDef *dst, c
       int rv = sscanf(floc,"%[^:]:%d:%d",file,&line,&column);
       if (rv!=3)
       {
-        msg("unable to read file loc from[%s]\n",floc);
+        msg("unable to read file:line:col location from string [%s]\n",floc);
         return;
       }
     }