improved documentation, better api documentation

doc/doxyfile.in

@@ -226,7 +226,7 @@ ALIASES += "instancemutex=\par Reentrant:\nAccess is locked with per instance mu
 ALIASES += "classmutex=\par Reentrant:\nAccess is locked with class static mutex @c "
 ALIASES += "license=\par License\n"
 ALIASES += "copy=\par Copyright\n"
-
+ALIASES += "api=\xrefitem api \"API Call\" \"\""
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"
 # will allow you to use the command class in the itcl::class meaning.
@@ -785,7 +785,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = @top_srcdir@/openpgp.js
+EXCLUDE                = @top_srcdir@/html/openpgp.js
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -2223,7 +2223,7 @@ DOT_IMAGE_FORMAT       = svg
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-INTERACTIVE_SVG        = YES
+INTERACTIVE_SVG        = NO
 
 # The DOT_PATH tag can be used to specify the path where the dot tool can be
 # found. If left blank, it is assumed the dot tool can be found in the path.

html/checknewuser.php

@@ -2,37 +2,33 @@
 /*! @file
 
     @id $Id$
+*/
+//       1         2         3         4         5         6         7         8
+// 45678901234567890123456789012345678901234567890123456789012345678901234567890
 
-    @see @ref apichecknewuser
+/// Check if a user exists
-
+/** Check if a user exists in the server's user table.
-    @page api Server API
-
-    @tableofcontents
-
-    @section apichecknewuser Check If User Exists
-
-    API-call checknewuser.php
-
-    Check if a user exists in the server's user table.
 
-    @param user user name to check
+    @param $user user name to check
     @return json encoded value:
       - 'user name as string', if user does exist
       - null, if user does not exist or in case of error
-*/
-//       1         2         3         4         5         6         7         8
-// 45678901234567890123456789012345678901234567890123456789012345678901234567890
 
+    @api Check If User Exists
+*/
+function checknewuser($user) {
   try {
     require_once("opendb.php");
-  $user = $db->real_escape_string($_REQUEST['user']);
+    $dbuser = $db->real_escape_string($user);
-  $q = $db->query("select * from user where name='$user';");
+    $q = $db->query("select * from user where name='$dbuser';");
     if ($q->num_rows==0) {
-    echo json_encode($_REQUEST['user']);
+      echo json_encode($user);
     } else {
       echo json_encode(null);
     }
   } catch (Exception $e) {
     echo json_encode(null);
   }
+}
+checknewuser($_REQUEST['user']);
 ?>

html/get.php

@@ -2,18 +2,15 @@
 /*! @file
 
     @id $Id$
+*/
+//       1         2         3         4         5         6         7         8
+// 45678901234567890123456789012345678901234567890123456789012345678901234567890
 
-    @see @ref apiget
-
-    @page api
-
-    @section apiget Get Messages
-
-    API-call get.php
 
-    Get all messages that are newer than start.
+/// Get new messages
+/** Get all messages that are newer than @c $start.
 
-    @param start Number of message to start with.
+    @param $start Number of message to start with.
     @return json encoded array of messages:
        @code
            [
@@ -25,16 +22,19 @@
              }, ...
            ]
        @endcode
+
+    @api Get New Messages
 */
-//       1         2         3         4         5         6         7         8
+function get($start) {
-// 45678901234567890123456789012345678901234567890123456789012345678901234567890
   try {
     require_once("opendb.php");
-  $start = $db->real_escape_string($_REQUEST['start']);
+    $start = $db->real_escape_string($start);
     $q = $db->query("select id, UNIX_TIMESTAMP(time) as time, user, msg from message where id>$start;");
     if ($q) echo json_encode($q->fetch_all(MYSQLI_ASSOC));
     else echo json_encode(null);
   } catch (Exception $e) {
     echo json_encode(null);
   }
+}
+get($_REQUEST['start']);
 ?>

html/login.php

@@ -2,35 +2,33 @@
 /*! @file
     
     @id $Id$
+*/
+//       1         2         3         4         5         6         7         8
+// 45678901234567890123456789012345678901234567890123456789012345678901234567890
 
-    @see @ref apilogin
-
-    @page api
-
-    @section apilogin Login
-
-    API-call login.php
 
-    Check if a user is consistent to the data in the server's database
+/// Verify a user
-    or create a user, if he does not yet exist in the @ref usertable
+/** Check if a user is consistent to the data in the server's database
+    or create a user, if he does not yet exist in the usertable
     (and the user name is available).
 
-    @param user user's name
+    @param $user user's name
-    @param pubkey user's public key
+    @param $pubkey user's public key
 
     @return json encoded status with text:
        - success() in case of success (user exists or has been created)
        - error() in case of mismatch
+
+    @api Verify a User
 */
-//       1         2         3         4         5         6         7         8
+function login($user, $pubkey) {
-// 45678901234567890123456789012345678901234567890123456789012345678901234567890
   try {
     require_once("opendb.php");
-  $user = $db->real_escape_string($_REQUEST['user']);
-  $pubkey = $db->real_escape_string($_REQUEST['pubkey']);
     if ($user=="safechat") error("username safechat is reserved for server");
-  $verify = gnupg_import($pgp, $_REQUEST['pubkey']);
+    $verify = gnupg_import($pgp, $pubkey);
     if (!$verify) error("wrong identity");
+    $user = $db->real_escape_string($user);
+    $pubkey = $db->real_escape_string($pubkey);
     $q = $db->query("select * from user where name='$user' and pubkey='$pubkey';");
     if ($q->num_rows==1) {
       success("user $user found on server");
@@ -44,4 +42,6 @@ try {
   } catch (Exception $e) {
     error("login failed");
   }
+}
+login($_REQUEST['user'], $_REQUEST['pubkey']);
 ?>

html/pubkey.php

@@ -2,18 +2,14 @@
 /*! @file
 
     @id $Id$
+*/
+//       1         2         3         4         5         6         7         8
+// 45678901234567890123456789012345678901234567890123456789012345678901234567890
 
-    @see @ref apipubkey
+/// Get a user's public key
-
+/** Get the public key of a user.
-    @page api
-
-    @section apipubkey Get Public Key
-
-    API-call pubkey.php
-
-    Get the public key of a user.
 
-    @param user Name of the user to ge public key from.
+    @param $user Name of the user to ge public key from.
 
     @return json encoded value:
      - @c null in case of error (user does not exist)
@@ -22,12 +18,13 @@
          pubkey: 'armored public key string'
        }
        @endcode
+
+    @api Get A User's Public Key
 */
-//       1         2         3         4         5         6         7         8
+function pubkey($user) {
-// 45678901234567890123456789012345678901234567890123456789012345678901234567890
   try {
-  require_once("usertable.php");
+    require_once("opendb.php");
-  $user = $db->real_escape_string($_REQUEST['user']);
+    $user = $db->real_escape_string($user);
     $q = $db->query("select pubkey from user where name='$user';");
     /* if ($q->num_rows!=1 && $user=="safechat") { */
     /*   require_once("optionstable.php"); */
@@ -42,4 +39,6 @@ try {
   } catch (Exception $e) {
     echo json_encode(null);
   }
+}
+pubkey($_REQUEST['user']);
 ?>

html/send.php

@@ -2,33 +2,30 @@
 /*! @file
 
     @id $Id$
+*/
+//       1         2         3         4         5         6         7         8
+// 45678901234567890123456789012345678901234567890123456789012345678901234567890
 
-    @see @ref apisend
+/// Send a message to the server
-
+/** Server checks if user exists and has
-    @page api
-
-    @section apisend Send Message To Server
-
-    API-call send.php
-
-    Send a message to the server. Sever checks if user exists and has
     a valid public key. More test could be added later.
 
-    @param user The name of the user that send the message.
+    @param $user The name of the user that send the message.
 
-    @param msg The armored signed and encrypted message. There is a
+    @param $msg The armored signed and encrypted message. There is a
                 limit of 100000 bytes for the message.
 
     @return
       - success() if the message has been stored successfully
       - error() in case of any error
+
+    @api Send Message to Server
 */
-//       1         2         3         4         5         6         7         8
+function send($user, $msg) {
-// 45678901234567890123456789012345678901234567890123456789012345678901234567890
   try {
     require_once("opendb.php");
-  $user = $db->real_escape_string($_REQUEST['user']);
+    $user = $db->real_escape_string($user);
-  $msg = $db->real_escape_string($_REQUEST['msg']);
+    $msg = $db->real_escape_string($msg);
     if (strlen($_REQUEST['msg'])>100000) error("message is too long");
     $q = $db->query("select pubkey from user where name='$user';");
     if (!$q || $q->num_rows!=1) error("user not found on server");
@@ -44,5 +41,6 @@ try {
     error_log("Error storing message: ".$e->message);
     error("storing message failed");
   }
-
+}
+send($_REQUEST['user'], $_REQUEST['msg']);
 ?>