more useful source docu

git-svn-id: https://silmor.de/svn/softmagic/smoke/trunk@24 6e3c4bff-ac9f-4ac1-96c5-d2ea494d3e33

diff --git a/Doxyfile-cpp b/Doxyfile-cpp
new file mode 100644 (file)
index 0000000..f6c259d
--- /dev/null
+++ b/Doxyfile-cpp
@@ -0,0 +1,4 @@
+@INCLUDE = Doxyfile.inc
+INPUT                  = src
+HTML_OUTPUT            = doc/source-cpp
+

diff --git a/Doxyfile-php b/Doxyfile-php
new file mode 100644 (file)
index 0000000..82c6e77
--- /dev/null
+++ b/Doxyfile-php
@@ -0,0 +1,4 @@
+@INCLUDE = Doxyfile.inc
+INPUT                  = www
+HTML_OUTPUT            = doc/source-php
+

diff --git a/Doxyfile b/Doxyfile.inc
similarity index 98%
rename from Doxyfile
rename to Doxyfile.inc
index 5c98a5a..b64fa2e 100644 (file)
--- a/Doxyfile
+++ b/Doxyfile.inc
@@ -1,9 +1,7 @@
-# Doxyfile 1.5.1-KDevelop
-
 #---------------------------------------------------------------------------
 # Project related configuration options
 #---------------------------------------------------------------------------
-PROJECT_NAME           = MagicSmoke.kdevelop
+PROJECT_NAME           = MagicSmoke
 PROJECT_NUMBER         = $VERSION$
 OUTPUT_DIRECTORY       = 
 CREATE_SUBDIRS         = NO
@@ -43,7 +41,7 @@ SUBGROUPING            = YES
 #---------------------------------------------------------------------------
 # Build related configuration options
 #---------------------------------------------------------------------------
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 EXTRACT_PRIVATE        = NO
 EXTRACT_STATIC         = YES
 EXTRACT_LOCAL_CLASSES  = YES
@@ -82,7 +80,7 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = /home/konrad/src/smoke
+#INPUT                  = /home/konrad/src/smoke
 FILE_PATTERNS          = *.c \
                          *.cc \
                          *.cxx \
@@ -105,6 +103,7 @@ FILE_PATTERNS          = *.c \
                          *.cs \
                          *.php \
                          *.php3 \
+                         *.php5 \
                          *.inc \
                          *.m \
                          *.mm \
@@ -164,7 +163,7 @@ IGNORE_PREFIX          =
 # configuration options related to the HTML output
 #---------------------------------------------------------------------------
 GENERATE_HTML          = YES
-HTML_OUTPUT            = html
+#HTML_OUTPUT            = html
 HTML_FILE_EXTENSION    = .html
 HTML_HEADER            = 
 HTML_FOOTER            = 
@@ -214,7 +213,7 @@ MAN_LINKS              = NO
 #---------------------------------------------------------------------------
 # configuration options related to the XML output
 #---------------------------------------------------------------------------
-GENERATE_XML           = yes
+GENERATE_XML           = NO
 XML_OUTPUT             = xml
 XML_SCHEMA             = 
 XML_DTD                = 

diff --git a/www/inc/cauth_hash.php b/www/inc/cauth_hash.php
index a6eedbb..879ea2b 100644 (file)
--- a/www/inc/cauth_hash.php
+++ b/www/inc/cauth_hash.php
@@ -11,6 +11,7 @@
 //
 //
 
+/**helper for Session::authenticate, using hash module*/
 function calcAuth($cha,$tok)
 {
        global $ClientAuthAlgo;

diff --git a/www/inc/cauth_mhash.php b/www/inc/cauth_mhash.php
index 7a1093e..7f32602 100644 (file)
--- a/www/inc/cauth_mhash.php
+++ b/www/inc/cauth_mhash.php
@@ -11,6 +11,7 @@
 //
 //
 
+/**helper for Session::authenticate, using mhash module*/
 function calcAuth($cha,$tok)
 {
        global $ClientAuthAlgo;

diff --git a/www/inc/cauth_string.php b/www/inc/cauth_string.php
index bcb2fbc..2f70290 100644 (file)
--- a/www/inc/cauth_string.php
+++ b/www/inc/cauth_string.php
@@ -11,6 +11,7 @@
 //
 //
 
+/**helper for Session::authenticate, using string module*/
 function calcAuth($key,$tok)
 {
        global $ClientAuthAlgo;

diff --git a/www/inc/db_mysql.php b/www/inc/db_mysql.php
index a2553ef..b07619d 100644 (file)
--- a/www/inc/db_mysql.php
+++ b/www/inc/db_mysql.php
@@ -1,4 +1,5 @@
 <?
+/**MySQL adaptation of DB-Engine*/
 class MysqlEngine extends DbEngine
 {
        /**prefix for table names*/

diff --git a/www/inc/db_scheme.php b/www/inc/db_scheme.php
index 41d0621..73c3011 100644 (file)
--- a/www/inc/db_scheme.php
+++ b/www/inc/db_scheme.php
@@ -1,4 +1,5 @@
 <?
+/**This class contains a high-level description of the database structure*/
 class DbScheme {
        private static $scheme;
        function __construct()

diff --git a/www/inc/parser.php b/www/inc/parser.php
index 9e59b8e..a5955d2 100644 (file)
--- a/www/inc/parser.php
+++ b/www/inc/parser.php
@@ -1,15 +1,15 @@
 <?
-//Helper class, should never be used directly
+/**Helper class, should never be used directly*/
 class PHelper
 {
        private $cont;
-       //create helper with array of text lines
+       /**create helper with array of text lines*/
        public function __construct(array $c)
        {
                $this->cont=$c;
                reset($this->cont);
        }
-       //return next line from array until end is reached
+       /**return next line from array until end is reached*/
        public function getLine()
        {
                $r=current($this->cont);
@@ -18,12 +18,12 @@ class PHelper
        }
 }
 
-//Parser class: see syntax docu for details
+/**Parser class: see syntax docu for details*/
 class Parser
 {
        private $vars=array();
        
-       //create parser object, initialize its internal state with optional file
+       /**create parser object, initialize its internal state with optional file*/
        public function __construct($fname="")
        {
                global $_SERVER;
@@ -31,38 +31,39 @@ class Parser
                if($fname!="")
                        $this->parseFile($fname);
        }
-       //parse a file, return parser-result
+       /**parse a file, return parser-result*/
        public function parseFile($fname)
        {
                global $template;
                $cont=file_get_contents($template.$fname);
                return $this->parse($cont);
        }
-       //parse a string, return parser-result
+       /**parse a string, return parser-result*/
        public function parse($str)
        {
                $cont=explode("\n",str_replace("\r","",$str));
                $help=new PHelper($cont);
                return $this->parseNormal($help);
        }
-       //set an internal variable
+       /**set an internal variable*/
        public function setVar($vname,$vval)
        {
                $this->vars[$vname]=$vval;
        }
+       /**set several internal variables array(variablename=>value)*/
        public function setVars(array $vs)
        {
                reset($vs);
                foreach($vs as $k => $v)
                        $this->vars[$k]=$v;
        }
-       //unset a variable
+       /**unset a variable*/
        public function unsetVar($vname)
        {
                if(isset($this->vars[$vname]))
                        unset($this->vars[$vname]);
        }
-       //get value of a variable (returns false if variable does not exist)
+       /**get value of a variable (returns false if variable does not exist)*/
        public function getVar($vname)
        {
                if(isset($this->vars[$vname]))
@@ -70,13 +71,13 @@ class Parser
                else
                        return false;
        }
-       //returns true if variable exists
+       /**returns true if variable exists*/
        public function haveVar($vname)
        {
                return isset($this->vars[$vname]);
        }
        
-       //internal: used by parse to load data
+       /**internal: used by parse to load data*/
        protected function parseNormal($help)
        {
                $out="";
@@ -91,7 +92,7 @@ class Parser
                        else $out.=$this->parseLine($line);
                }
        }
-       //internal: replace variables on a line
+       /**internal: replace variables on a line*/
        protected function parseLine($line)
        {
                $ak=array();
@@ -102,7 +103,7 @@ class Parser
                }
                return str_replace($ak,$av,$line)."\n";
        }
-       //internal: handle an #if statement
+       /**internal: handle an #if statement*/
        protected function parseIf($help,$line)
        {
                //parse if-line
@@ -155,6 +156,7 @@ class Parser
                        }
                }
        }
+       /**internal: handle #set statement*/
        protected function parseSet($help,$line)
        {
                //parse set-line

diff --git a/www/inc/session.php b/www/inc/session.php
index 9f76808..cf30a77 100644 (file)
--- a/www/inc/session.php
+++ b/www/inc/session.php
@@ -14,7 +14,7 @@
 //prune session cache
 $db->deleteRows("session","timeout<=".time());
 
-/**initiate new session*/
+/**initiate new session - $rand should contain some food for the random number generator (from the host request)*/
 function newSession($rand)
 {
        global $db,$ClientAuthTimeout;
@@ -52,6 +52,7 @@ class Session
        private $sessid="";
        private $user="";
        
+       /**construct the session object, check validity*/
        public function __construct()
        {
                global $_SERVER,$db;
@@ -64,16 +65,19 @@ class Session
                }
        }
        
+       /**returns true if the session exists, it may still be temporary and unauthenticated*/
        public function isValid()
        {
                return $this->sessid!="";
        }
        
+       /**returns true if the session is actually authenticated*/
        public function isAuthenticated()
        {
                return $this->user!="";
        }
        
+       /**helber function for authenticate*/
        protected function xdie($str)
        {
                //debug version:
@@ -82,6 +86,7 @@ class Session
                exit();
        }
        
+       /**runs authentication against the user request*/
        public function authenticate()
        {
                global $db,$REQUESTDATA;

diff --git a/www/machine.php b/www/machine.php
index 06e1474..a248079 100644 (file)
--- a/www/machine.php
+++ b/www/machine.php
@@ -9,17 +9,19 @@ if($_SERVER["REQUEST_METHOD"] != "POST" || !isset($_SERVER["HTTP_X_MAGICSMOKE_RE
 header("Content-Type: application/x-MagicSmoke");
 
 //check whether the request is known
-// all valid requests must be listed here (in lower case)
+/**all valid requests must be listed here (in lower case)*/
 $ALLOWEDREQUESTS=array(
        "serverinfo", //info request
        "startsession","sessionauth","closesession", //session requests
        "blah" //...
 );
+/**contains the low-level request name from the client*/
 $SMOKEREQUEST=strtolower($_SERVER["HTTP_X_MAGICSMOKE_REQUEST"]);
 if(!in_array($SMOKEREQUEST,$ALLOWEDREQUESTS)){
        header("X-MagicSmoke-Status: InvalidRequest");
        die("Invalid Request, please use the MagicSmoke Client with this page.");
 }
+/**contains the low-level request data from the client*/
 $REQUESTDATA="";
 if(isset($HTTP_RAW_POST_DATA)){
        $REQUESTDATA=$HTTP_RAW_POST_DATA;
@@ -63,6 +65,7 @@ if($SMOKEREQUEST=="closesession"){
 
 //all others need a valid session, check it
 //check session
+/**session object*/
 $session=new Session;
 if(!$session->isValid()){
        header("X-MagicSmoke-Status: Unauthenticated");