From 12cce7eac519786066003173ab072505f2ad8bb0 Mon Sep 17 00:00:00 2001
From: Bent Bisballe Nyeng <deva@aasimon.org>
Date: Fri, 13 Apr 2012 13:48:32 +0200
Subject: Documentation.

---
 client/docgen/doc.h            |  3 ++
 client/docgen/docgen.cc        | 87 ++++++++++++++++++++++++++++++++++++------
 client/docgen/generate.cc      | 40 ++++++++++++-------
 client/docgen/parse.cc         | 18 +++++++++
 client/docgen/style.css        |  5 +++
 client/luadb.cc                |  8 ++--
 client/luadb.h                 | 53 +++++++++++++++++++++++++
 client/widgets/altcombobox.h   |  1 +
 client/widgets/button.h        |  1 +
 client/widgets/checkbox.h      |  1 +
 client/widgets/checkgroupbox.h |  1 +
 client/widgets/combobox.h      |  1 +
 client/widgets/datetime.h      |  1 +
 client/widgets/groupbox.h      |  1 +
 client/widgets/label.h         |  1 +
 client/widgets/lineedit.h      |  1 +
 client/widgets/listbox.h       |  1 +
 client/widgets/metawidget.h    |  1 +
 client/widgets/multilist.h     |  1 +
 client/widgets/radiobuttons.h  |  1 +
 client/widgets/textedit.h      |  1 +
 client/widgets/widget.h        |  1 +
 client/widgets/window.h        |  1 +
 23 files changed, 202 insertions(+), 28 deletions(-)

(limited to 'client')

diff --git a/client/docgen/doc.h b/client/docgen/doc.h
index ae693f5..5678476 100644
--- a/client/docgen/doc.h
+++ b/client/docgen/doc.h
@@ -69,6 +69,9 @@ public:
   QString title;
   QString name;
   QString tag;
+  bool serverside;
+  bool clientside;
+  QString classname;
   QString extends; 
   bool container;
   QString description;
diff --git a/client/docgen/docgen.cc b/client/docgen/docgen.cc
index e4af0a3..4eb2e08 100644
--- a/client/docgen/docgen.cc
+++ b/client/docgen/docgen.cc
@@ -32,6 +32,7 @@
 #include <QDir>
 #include <QMap>
 #include <QDate>
+#include <QFileInfo>
 
 #include <stdio.h>
 
@@ -39,7 +40,9 @@
 #include "parse.h"
 #include "generate.h"
 
-#define INPUT "../widgets"
+#define WIDGETS_DIR "../widgets"
+#define SERVER_DIR "../../server/src"
+#define CLIENT_DIR ".."
 #define OUTPUT "html"
 
 QString output;
@@ -94,16 +97,46 @@ void writeIndex(QMap<QString, Doc> &docs)
   out += "<h1>Pracro "VERSION" Documentation</h1>\n";
   out += "<h2>Overview</h2>\n";
 
+  out += "<h3>Clientside</h3>\n";
+  out += "<h4>Widgets</h4>\n";
   out += "<ul>\n";
   QMap<QString, Doc>::iterator i = docs.begin();
   while(i != docs.end()) {
     Doc &doc = *i;
-    out += "<li><a href=\""+doc.name+".html\">["+doc.name+"]</a> - "+
-      doc.title+"</li>\n";
+    if(doc.tag != "") {
+      out += "<li><a href=\""+doc.name+".html\">["+doc.name+"]</a> - "+
+        doc.title+"</li>\n";
+    }
+    i++;
+  }
+  out += "</ul>\n";
+  out += "<h4>Classes</h4>\n";
+  out += "<ul>\n";
+  i = docs.begin();
+  while(i != docs.end()) {
+    Doc &doc = *i;
+    if(doc.classname != "" && doc.clientside) {
+      out += "<li><a href=\""+doc.name+".html\">["+doc.name+"]</a> - "+
+        doc.title+"</li>\n";
+    }
     i++;
   }
   out += "</ul>\n";
 
+  out += "<h3>Serverside</h3>\n";
+  out += "<ul>\n";
+  i = docs.begin();
+  while(i != docs.end()) {
+    Doc &doc = *i;
+    if(doc.classname != "" && doc.serverside) {
+      out += "<li><a href=\""+doc.name+".html\">["+doc.name+"]</a> - "+
+        doc.title+"</li>\n";
+    }
+    i++;
+  }
+  out += "</ul>\n";
+
+
   QFile::remove(output + "/index.html");
   QFile ofile(output + "/index.html");
   ofile.open(QIODevice::ReadWrite | QIODevice::Text);
@@ -133,15 +166,47 @@ int main(int argc, char *argv[])
   QFile::remove(output + "/style.css");
   QFile::copy("style.css", output + "/style.css");
 
-  QDir dir(INPUT);
-  QStringList filter; filter << "*.h";
-  dir.setNameFilters(filter);
+  QStringList files;
+
+  // Widgets
+  {
+    QDir dir(WIDGETS_DIR);
+    QStringList filter; filter << "*.h";
+    dir.setNameFilters(filter);
+    if(!dir.exists()) return 1;
+    QFileInfoList inflst = dir.entryInfoList(QDir::Files);
+    foreach(QFileInfo inf, inflst) {
+      files.append(inf.absoluteFilePath());
+    }
+  }
+
+  // Client
+  {
+    QDir dir(CLIENT_DIR);
+    QStringList filter; filter << "*.h";
+    dir.setNameFilters(filter);
+    if(!dir.exists()) return 1;
+    QFileInfoList inflst = dir.entryInfoList(QDir::Files);
+    foreach(QFileInfo inf, inflst) {
+      files.append(inf.absoluteFilePath());
+    }
+  }
+
+  // Server
+  {
+    QDir dir(SERVER_DIR);
+    QStringList filter; filter << "*.h";
+    dir.setNameFilters(filter);
+    if(!dir.exists()) return 1;
+    QFileInfoList inflst = dir.entryInfoList(QDir::Files);
+    foreach(QFileInfo inf, inflst) {
+      files.append(inf.absoluteFilePath());
+    }
+  }
 
-  if(!dir.exists()) return 1;
-  QStringList l = dir.entryList(QDir::Files);
-  foreach(QString file, l) {
-    Doc doc = parse(QString(INPUT) + "/" + file);
-    if(doc.title != "" || doc.tag != "")
+  foreach(QString file, files) {
+    Doc doc = parse(file);
+    if(doc.title != "" || doc.tag != "" || doc.classname != "")
       docs[doc.name] = doc;
   }
 
diff --git a/client/docgen/generate.cc b/client/docgen/generate.cc
index b521f1f..f418b24 100644
--- a/client/docgen/generate.cc
+++ b/client/docgen/generate.cc
@@ -219,6 +219,18 @@ QString generate(Doc &doc, QMap<QString, QVector<Method> > &meths,
       highlight("<" + doc.tag + " />", xml) + "</pre></div>\n";
   }
 
+  if(doc.serverside)
+    out += "      <div class=\"availablility\">Available serverside.</div>\n";
+
+  if(doc.clientside)
+    out += "      <div class=\"availablility\">Available clientside.</div>\n";
+
+
+  if(doc.classname != "" ){
+    out += "      <div class=\"classname\">Class<pre class=\"code\">" +
+      doc.classname + "</pre></div>\n";
+  }
+
   if(doc.container) {
     out += "      <div class=\"container\">Widget is a container.</div>\n";
   }
@@ -248,21 +260,23 @@ QString generate(Doc &doc, QMap<QString, QVector<Method> > &meths,
 
   out += generateExamples(doc.examples, xml);
 
-  out += "      <h2>Attributes</h2>\n";
-  out += "      <div class=\"attributes\">\n";
-  if(doc.attributes.size()) {
-    out += generateAttributes(doc.attributes);
-  }
+  if(doc.tag != "") {
+    out += "      <h2>Attributes</h2>\n";
+    out += "      <div class=\"attributes\">\n";
+    if(doc.attributes.size()) {
+      out += generateAttributes(doc.attributes);
+    }
 
-  QMap<QString, QVector<Attribute> >::iterator i = atts.begin();
-  while(i != atts.end()) {
-    out += "      <h3>Attributes inherited from <a href=\"" + i.key() +
-      ".html\">"+i.key()+"</a>:</h3>\n";
-    out += generateAttributes(i.value());
-    i++;
+    QMap<QString, QVector<Attribute> >::iterator i = atts.begin();
+    while(i != atts.end()) {
+      out += "      <h3>Attributes inherited from <a href=\"" + i.key() +
+        ".html\">"+i.key()+"</a>:</h3>\n";
+      out += generateAttributes(i.value());
+      i++;
+    }
+    out += "      </div>\n";
   }
-  out += "      </div>\n";
- 
+
   out += generateMethodOverview(doc, meths);
 
   out += "      <h2>Methods</h2>\n";
diff --git a/client/docgen/parse.cc b/client/docgen/parse.cc
index 64c2aa7..0354f57 100644
--- a/client/docgen/parse.cc
+++ b/client/docgen/parse.cc
@@ -89,6 +89,8 @@ Doc parse(QString filename)
 {
   Doc doc;
   doc.container = false;
+  doc.serverside = false;
+  doc.clientside = false;
 
   QFileInfo fi(filename);
   QString name = fi.fileName();
@@ -134,10 +136,26 @@ Doc parse(QString filename)
         continue;
       }
 
+      if(state == none && line.left(6) == "@class") {
+        doc.classname = line.right(line.length() - line.indexOf(" ") - 1);
+        doc.name = doc.classname;
+        continue;
+      }
+
       if(state == none && line.left(8) == "@extends") {
         doc.extends = line.right(line.length() - line.indexOf(" ") - 1);
         continue;
       }
+
+      if(state == none && line.left(11) == "@serverside") {
+        doc.serverside = true;
+        continue;
+      }
+
+      if(state == none && line.left(11) == "@clientside") {
+        doc.clientside = true;
+        continue;
+      }
       
       if(state == none && line.left(11) == "@screenshot") {
         Screenshot s;
diff --git a/client/docgen/style.css b/client/docgen/style.css
index e938648..17f087e 100644
--- a/client/docgen/style.css
+++ b/client/docgen/style.css
@@ -26,6 +26,11 @@ a:hover {
 }
 
 .doc .tagname {
+    font-size: 1.5em;
+    text-align: center;
+}
+.doc .classname {
+    font-size: 1.5em;
     text-align: center;
 }
 .doc .extends {}
diff --git a/client/luadb.cc b/client/luadb.cc
index 317831f..a848f36 100644
--- a/client/luadb.cc
+++ b/client/luadb.cc
@@ -77,7 +77,7 @@ typedef struct db_userdata {
   DB *db;
 } db_userdata;
 
-static int db_value(lua_State *L)
+int db_value(lua_State *L)
 {
   db_userdata *dbu;
 
@@ -91,7 +91,7 @@ static int db_value(lua_State *L)
   return 1;
 }
 
-static int db_exec(lua_State *L)
+int db_exec(lua_State *L)
 {
   db_userdata *dbu;
 
@@ -105,7 +105,7 @@ static int db_exec(lua_State *L)
   return 0;
 }
 
-static int db_next(lua_State *L)
+int db_next(lua_State *L)
 {
   db_userdata *dbu;
 
@@ -119,7 +119,7 @@ static int db_next(lua_State *L)
   return 1;
 }
 
-static int db_new(lua_State *L)
+int db_new(lua_State *L)
 {
   const char *driver = luaL_checkstring(L, 1);
   const char *host = luaL_checkstring(L, 2);
diff --git a/client/luadb.h b/client/luadb.h
index a87baf5..91c8777 100644
--- a/client/luadb.h
+++ b/client/luadb.h
@@ -30,6 +30,59 @@
 
 #include <lua.hpp>
 
+/***
+ * Database Class
+ * @class DB
+ * @clientside
+ * The DB class connects and handles communication with the an SQL server using
+ * the QDatabase API.
+ */
+
+/***
+ * @method object DB.new(string driver, string host, string database, string user, string password, int port)
+ * Create a new DB connection object.
+ * @param driver A string containing the QT SQL driver name. QPSQL: postgresql
+ * driver.
+ * @param host The hostname to connect to.
+ * @param database The database to open.
+ * @param user The username to use for authentication.
+ * @param password The password to use for authentication.
+ * @param port The port to connect to.
+ * @return The newly created communication object.
+ * @example Create a new database object:
+ * px = DB.new('QPSQL', 'localhost', 'mydb', 'user01', 'verysecret', '5432')
+ */
+int db_new(lua_State *L);
+
+/***
+ * @method nil exec(string query)
+ * Execute an SQL query.
+ * @param query A string containing the SQL query to execute.
+ */ 
+int db_exec(lua_State *L);
+
+/***
+ * @method string value(int index)
+ * Get current value from the result of the last query.
+ * @param index The column index number to use for the value retrieval.
+ * @return A string containing the value in the result cell.
+ */
+int db_value(lua_State *L);
+
+/***
+ * @method boolean next()
+ * Iterate to next row in result set.
+ * @return true if another row is availble, false if the end of the list has
+ * been reached.
+ * @example Iterate through a result list and print the value in column 0 in each row:
+ * while db:next()
+ * do
+ *   local item = db:value(0)
+ *   print(item)
+ * end
+ */
+int db_next(lua_State *L);
+
 void register_db(lua_State *L);
 
 #endif/*__PRACRO_LUADB_H__*/
diff --git a/client/widgets/altcombobox.h b/client/widgets/altcombobox.h
index b0fb61c..73dee10 100644
--- a/client/widgets/altcombobox.h
+++ b/client/widgets/altcombobox.h
@@ -43,6 +43,7 @@
 /***
  * ComboBox Widget with Alternate Value
  * @tag altcombobox
+ * @clientside
  * @extends combobox
  * @screenshot Example: altitem selected.
  * <altcombobox name="ex" layout="vbox" value="altitem" type="select">
diff --git a/client/widgets/button.h b/client/widgets/button.h
index 0bd7db9..d9053a6 100644
--- a/client/widgets/button.h
+++ b/client/widgets/button.h
@@ -34,6 +34,7 @@
 /***
  * PushButton Widget
  * @tag button
+ * @clientside
  * @screenshot Example button
  * <button caption="Click me"/>
  * @screenshot Example cancel button
diff --git a/client/widgets/checkbox.h b/client/widgets/checkbox.h
index ce31a62..5fef7cb 100644
--- a/client/widgets/checkbox.h
+++ b/client/widgets/checkbox.h
@@ -38,6 +38,7 @@
 /***
  * CheckBox Widget
  * @tag checkbox
+ * @clientside
  * @screenshot An example checkbox
  * <checkbox name="example" truevalue="true" falsevalue="false" value="true"
  *           caption="A simple checkbox"/>
diff --git a/client/widgets/checkgroupbox.h b/client/widgets/checkgroupbox.h
index 5dfa7fb..96056a4 100644
--- a/client/widgets/checkgroupbox.h
+++ b/client/widgets/checkgroupbox.h
@@ -41,6 +41,7 @@
 /***
  * Checkable GroupBox Widget
  * @tag checkgroupbox
+ * @clientside
  * @extends checkbox
  * @screenshot Example 1: type="framed"
  * <checkgroupbox name="example" caption="Example" type="framed" layout="vbox"
diff --git a/client/widgets/combobox.h b/client/widgets/combobox.h
index bf61b1a..448a0ff 100644
--- a/client/widgets/combobox.h
+++ b/client/widgets/combobox.h
@@ -40,6 +40,7 @@
 /***
  * ComboBox Widget
  * @tag combobox
+ * @clientside
  * @screenshot Example
  * <combobox name="ex" layout="vbox" value="item" type="select">
  *   <item caption="Item" value="item"/>
diff --git a/client/widgets/datetime.h b/client/widgets/datetime.h
index 84df018..a36d87b 100644
--- a/client/widgets/datetime.h
+++ b/client/widgets/datetime.h
@@ -35,6 +35,7 @@
 /***
  * Date and Time Widget
  * @tag datetime
+ * @clientside
  * @screenshot Example with fuzziness="1" and value="1234567890"
  * <datetime name="x" fuzziness="1" value="1234567890"/>
  * @screenshot Example with fuzziness="7" and value="1234567890"
diff --git a/client/widgets/groupbox.h b/client/widgets/groupbox.h
index 58e52bb..9198a5a 100644
--- a/client/widgets/groupbox.h
+++ b/client/widgets/groupbox.h
@@ -37,6 +37,7 @@
 /***
  * Layout or Frame Widget 
  * @tag frame
+ * @clientside
  * @screenshot Example with caption.
  * <frame caption="Caption" layout="vbox">
  *   <label caption="Label"/>
diff --git a/client/widgets/label.h b/client/widgets/label.h
index b303d0d..eae97b8 100644
--- a/client/widgets/label.h
+++ b/client/widgets/label.h
@@ -34,6 +34,7 @@
 /***
  * Label Widget
  * @tag label
+ * @clientside
  * @screenshot Example
  * <label width="300" caption="A nice label with a caption"/>
  * @extends widget
diff --git a/client/widgets/lineedit.h b/client/widgets/lineedit.h
index 08230a6..d482c15 100644
--- a/client/widgets/lineedit.h
+++ b/client/widgets/lineedit.h
@@ -39,6 +39,7 @@
 /***
  * Line Edit Widget
  * @tag lineedit
+ * @clientside
  * @screenshot Example
  * <lineedit name="myname" value="some text"/>
  * @extends widget
diff --git a/client/widgets/listbox.h b/client/widgets/listbox.h
index 82c5dfc..f9d967a 100644
--- a/client/widgets/listbox.h
+++ b/client/widgets/listbox.h
@@ -38,6 +38,7 @@
 
 /***
  * ListBox Widget
+ * @clientside
  * @tag listbox
  * @screenshot Example
  * <listbox name="x" value="item1">
diff --git a/client/widgets/metawidget.h b/client/widgets/metawidget.h
index c6bf5d0..c6a7224 100644
--- a/client/widgets/metawidget.h
+++ b/client/widgets/metawidget.h
@@ -36,6 +36,7 @@
 
 /***
  * Meta Widget
+ * @clientside
  * @extends widget
  * @tag metawidget
  * @screenshot An example of a metawidget with two inner widgets. The metawidget is not in itself visible.
diff --git a/client/widgets/multilist.h b/client/widgets/multilist.h
index f7da8fa..a7c5332 100644
--- a/client/widgets/multilist.h
+++ b/client/widgets/multilist.h
@@ -37,6 +37,7 @@
 /***
  * Multi List Widget
  * @tag multilist
+ * @clientside
  * @container
  * @screenshot Example of multilist containing a metawidget.
  * <multilist name="x" layout="vbox" innerwidget="in" value="Abc: Def
diff --git a/client/widgets/radiobuttons.h b/client/widgets/radiobuttons.h
index 4b9ce67..e09d4e8 100644
--- a/client/widgets/radiobuttons.h
+++ b/client/widgets/radiobuttons.h
@@ -35,6 +35,7 @@
 /***
  * Radio Button Group Widget
  * @tag radiobuttons
+ * @clientside
  * @extends widget
  * @screenshot Example with four radiobuttons
  * <radiobuttons name="x" value="item2">
diff --git a/client/widgets/textedit.h b/client/widgets/textedit.h
index 542dd6f..fbbb040 100644
--- a/client/widgets/textedit.h
+++ b/client/widgets/textedit.h
@@ -35,6 +35,7 @@
 /***
  * Multiline Text Edit Widget
  * @tag textedit
+ * @clientside
  * @screenshot Example of a textedit.
  * <textedit name="x" value="This is a multiline textfield.
  * It may contain all text in the universe, it will simply add a scrollbar."/>
diff --git a/client/widgets/widget.h b/client/widgets/widget.h
index 6199aa4..f2bf278 100644
--- a/client/widgets/widget.h
+++ b/client/widgets/widget.h
@@ -44,6 +44,7 @@
 /***
  * Virtual Base Widget
  * This tag is purely virtual. It is inherited by all other widgets.
+ * @clientside
  * @att name The name of the widget. This is also the name used by the scripts.
  * @att value The initial value of the widget. It is overwritten if there is a
  * map with a recent value or if the database contains a recent value. 
diff --git a/client/widgets/window.h b/client/widgets/window.h
index ea3af0a..8fb5c59 100644
--- a/client/widgets/window.h
+++ b/client/widgets/window.h
@@ -34,6 +34,7 @@
  * Widgets Outer Container
  * @tag widgets
  * @container
+ * @clientside
  * This is the outer tag of the macro widgets.
  * @att caption This is the name that will be shown in the macro.
  * @att layout this is the layout that is used by the macro. It can be one of
-- 
cgit v1.2.3