more docs

html/login.php

@@ -1,4 +1,29 @@
 <?php
+/*! @file
+    
+    @id $Id$
+
+    @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
+    or create a user, if he does not yet exist in the @ref usertable
+    (and the user name is available).
+
+    @param user user's name
+    @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
+*/
+//       1         2         3         4         5         6         7         8
+// 45678901234567890123456789012345678901234567890123456789012345678901234567890
 try {
   require_once("usertable.php");
   $user = $db->real_escape_string($_REQUEST['user']);
@@ -18,6 +43,6 @@ try {
     error("server database defect");
   }
 } catch (Exception $e) {
-  echo json_encode(array('success' => false, 'txt' => "login failed"));
+  error("login failed");
 }
 ?>