phpdoc comments

darcs-hash:20050114164057-9977f-e4936fde9037c65c3f32c30b31b2b7df35732f3a.gz

12 files changed, 648 insertions, 168 deletions

diff --git a/inc/DifferenceEngine.php b/inc/DifferenceEngine.php
index a4af4b193..6a0b6d176 100644
--- a/inc/DifferenceEngine.php
+++ b/inc/DifferenceEngine.php
@@ -1,11 +1,12 @@
 <?php
-
-// A PHP diff engine for phpwiki. (Taken from phpwiki-1.3.3)
-//
-// Copyright (C) 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org>
-// You may copy this code freely under the conditions of the GPL.
-//
-
+/**
+ * A PHP diff engine for phpwiki. (Taken from phpwiki-1.3.3)
+ *
+ * Additions by Axel Boldt for MediaWiki
+ *
+ * @copyright (C) 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org>
+ * @license  You may copy this code freely under the conditions of the GPL.
+ */
 define('USE_ASSERTS', function_exists('assert'));
 
 class _DiffOp {
@@ -191,7 +192,8 @@ class _DiffEngine
 	}
 	
 
-	/* Divide the Largest Common Subsequence (LCS) of the sequences
+	/**
+   * Divide the Largest Common Subsequence (LCS) of the sequences
 	 * [XOFF, XLIM) and [YOFF, YLIM) into NCHUNKS approximately equally
 	 * sized segments.
 	 *
@@ -306,7 +308,8 @@ class _DiffEngine
 	return $end;
 	}
 
-	/* Find LCS of two sequences.
+	/**
+   * Find LCS of two sequences.
 	 *
 	 * The results are recorded in the vectors $this->{x,y}changed[], by
 	 * storing a 1 in the element for each line that is an insertion
@@ -362,7 +365,8 @@ class _DiffEngine
 		}
 	}
 
-	/* Adjust inserts/deletes of identical lines to join changes
+	/**
+   * Adjust inserts/deletes of identical lines to join changes
 	 * as much as possible.
 	 *
 	 * We do something when a run of changed lines include a
diff --git a/inc/auth.php b/inc/auth.php
index a34fc0a47..3db9cc21a 100644
--- a/inc/auth.php
+++ b/inc/auth.php
@@ -1,40 +1,61 @@
 <?
-require_once("inc/common.php");
-require_once("inc/io.php");
-require_once("inc/blowfish.php");
-# load the the auth functions
-require_once('inc/auth_'.$conf['authtype'].'.php');
-
-# some ACL level defines
-define('AUTH_NONE',0);
-define('AUTH_READ',1);
-define('AUTH_EDIT',2);
-define('AUTH_CREATE',4);
-define('AUTH_UPLOAD',8);
-define('AUTH_GRANT',255);
-
-if($conf['useacl']){
-  auth_login($_REQUEST['u'],$_REQUEST['p'],$_REQUEST['r']);
-  # load ACL into a global array
-  $AUTH_ACL = file('conf/acl.auth');
-}
+/**
+ * Authentication library
+ *
+ * Including this file will automatically try to login
+ * a user by calling auth_login()
+ *
+ * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
+ * @author     Andreas Gohr <andi@splitbrain.org>
+ */
+
+  require_once("inc/common.php");
+  require_once("inc/io.php");
+  require_once("inc/blowfish.php");
+  // load the the auth functions
+  require_once('inc/auth_'.$conf['authtype'].'.php');
+
+  // some ACL level defines
+  define('AUTH_NONE',0);
+  define('AUTH_READ',1);
+  define('AUTH_EDIT',2);
+  define('AUTH_CREATE',4);
+  define('AUTH_UPLOAD',8);
+  define('AUTH_GRANT',255);
+
+  if($conf['useacl']){
+    auth_login($_REQUEST['u'],$_REQUEST['p'],$_REQUEST['r']);
+    // load ACL into a global array
+    $AUTH_ACL = file('conf/acl.auth');
+  }
 
 /**
  * This tries to login the user based on the sent auth credentials
  *
- * FIXME: Description no longer valid!
- *
  * The authentication works like this: if a username was given
- * a new login is assumed and user/password are checked - if they
- * are correct a random authtoken is created which is stored in
- * the session _and_ in a cookie.
- * The user stays logged in as long as the session and the cookie
- * match. This still isn't the securest method but requires an
- * attacker to steal an existing session _and_ the authtoken
- * cookie. The actual password is only transfered once per login.
- * 
+ * a new login is assumed and user/password are checked. If they
+ * are correct the password is encrypted with blowfish and stored
+ * together with the username in a cookie - the same info is stored
+ * in the session, too. Additonally a browserID is stored in the
+ * session.
+ *
+ * If no username was given the cookie is checked: if the username,
+ * crypted password and browserID match between session and cookie
+ * no further testing is done and the user is accepted
+ *
+ * If a cookie was found but no session info was availabe the
+ * blowish encrypted password from the cookie is decrypted and
+ * together with username rechecked by calling this function again.
+ *
  * On a successful login $_SERVER[REMOTE_USER] and $USERINFO
  * are set.
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param   string  $user    Username
+ * @param   string  $pass    Cleartext Password
+ * @param   bool    $sticky  Cookie should not expire
+ * @return  bool             true on successful auth
 */
 function auth_login($user,$pass,$sticky=false){
   global $USERINFO;
@@ -72,7 +93,7 @@ function auth_login($user,$pass,$sticky=false){
     $cookie = base64_decode($_COOKIE['DokuWikiAUTH']);
     list($user,$sticky,$pass) = split('\|',$cookie,3);
     // get session info
-   	$session = $_SESSION[$conf['title']]['auth'];
+    $session = $_SESSION[$conf['title']]['auth'];
 
     if($user && $pass){
       // we got a cookie - see if we can trust it
@@ -100,6 +121,10 @@ function auth_login($user,$pass,$sticky=false){
  *
  * This is neither unique nor unfakable - still it adds some
  * security
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ *
+ * @return  string  a MD5 sum of various browser headers
  */
 function auth_browseruid(){
   $uid  = '';
@@ -112,6 +137,15 @@ function auth_browseruid(){
 
 /**
  * Creates a random key to encrypt the password in cookies
+ *
+ * This function tries to read the password for encrypting
+ * cookies from $conf['datadir'].'/.cache/cookiesalt'
+ * if no such file is found a random key is created and
+ * and stored in this file.
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ *
+ * @return  string
  */
 function auth_cookiesalt(){
   global $conf;
@@ -127,6 +161,8 @@ function auth_cookiesalt(){
 /**
  * This clears all authenticationdata and thus log the user
  * off
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function auth_logoff(){
   global $conf;
@@ -140,7 +176,14 @@ function auth_logoff(){
 }
 
 /**
- * Convinience function for auth_aclcheck
+ * Convinience function for auth_aclcheck()
+ *
+ * This checks the permissions for the current user
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param  string  $id  page ID
+ * @return int          permission level
  */
 function auth_quickaclcheck($id){
   global $conf;
@@ -153,6 +196,13 @@ function auth_quickaclcheck($id){
 /**
  * Returns the maximum rights a user has for
  * the given ID or its namespace
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param  string  $id     page ID
+ * @param  string  $user   Username
+ * @param  array   $groups Array of groups the user is in
+ * @return int             permission level
  */
 function auth_aclcheck($id,$user,$groups){
   global $conf;
@@ -234,7 +284,10 @@ function auth_aclcheck($id,$user,$groups){
 /**
  * Create a pronouncable password
  *
- * @see: http://www.phpbuilder.com/annotate/message.php3?id=1014451
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ * @link    http://www.phpbuilder.com/annotate/message.php3?id=1014451
+ *
+ * @return string  pronouncable password
  */
 function auth_pwgen(){
   $pw = '';
@@ -257,7 +310,9 @@ function auth_pwgen(){
 /**
  * Sends a password to the given user
  *
- * returns true on success
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ *
+ * @return bool  true on success
  */
 function auth_sendPassword($user,$password){
   global $conf;
@@ -281,10 +336,13 @@ function auth_sendPassword($user,$password){
 }
 
 /**
- * The new user registration - we get our info directly from
- * $_POST
+ * Register a new user
+ * 
+ * This registers a new user - Data is read directly from $_POST
  *
- * It returns true on success and false on any error
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ *
+ * @return bool  true on success, false on any error
  */
 function register(){
   global $lang;
@@ -333,9 +391,12 @@ function register(){
 /**
  * Uses a regular expresion to check if a given mail address is valid
  *
- * @see http://www.webmasterworld.com/forum88/135.htm
- *
  * May not be completly RFC conform!
+ * 
+ * @link    http://www.webmasterworld.com/forum88/135.htm
+ *
+ * @param   string $email the address to check
+ * @return  bool          true if address is valid
  */
 function isvalidemail($email){
   return eregi("^[0-9a-z]([-_.]?[0-9a-z])*@[0-9a-z]([-.]?[0-9a-z])*\\.[a-z]{2,4}$", $email);
diff --git a/inc/auth_ldap.php b/inc/auth_ldap.php
index 2872e710f..c1ff55706 100644
--- a/inc/auth_ldap.php
+++ b/inc/auth_ldap.php
@@ -1,15 +1,21 @@
 <?php
 /**
- * This is used to authenticate against an LDAP server
+ * LDAP authentication backend
  * 
  * tested with openldap 2.x on Debian only
  *
  * PHPs LDAP extension is needed
+ *
+ * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
+ * @author     Andreas Gohr <andi@splitbrain.org>
  */
 
 /**
- * connects to the ldap server and holds the connection
- * in global scope for multiple use
+ * Connect to the LDAP server
+ *
+ * Holds the connection in global scope for multiple use
+ *
+ * @author     Andreas Gohr <andi@splitbrain.org>
  */
 function auth_ldap_connect(){
   global $LDAP_CONNECTION;
@@ -34,12 +40,14 @@ function auth_ldap_connect(){
 }
 
 /**
- * required auth function
+ * Check user+password [required auth function]
  *
  * Checks if the given user exists and the given
- * plaintext password is correct
+ * plaintext password is correct by trying to bind
+ * to the LDAP server
  *
- * It does so by trying to connect to the LDAP server
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ * @return  bool
  */
 function auth_checkPass($user,$pass){
   global $conf;
@@ -62,7 +70,7 @@ function auth_checkPass($user,$pass){
 }
 
 /**
- * Required auth function
+ * Return user info [required auth function]
  *
  * Returns info about the given user needs to contain
  * at least these fields:
@@ -72,10 +80,12 @@ function auth_checkPass($user,$pass){
  * grps array   list of groups the user is in
  *
  * This LDAP specific function returns the following
- * addional fields
+ * addional fields:
  *
  * dn   string  distinguished name (DN)
  * uid  string  Posix User ID
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function auth_getUserData($user){
   global $conf;
@@ -125,9 +135,11 @@ function auth_getUserData($user){
 }
 
 /**
- * Required auth function
+ * Create a new User [required auth function]
  *
  * Not implemented
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function auth_createUser($user,$name,$mail){
   msg("Sorry. Creating users is not supported by the LDAP backend",-1);
diff --git a/inc/auth_mysql.php b/inc/auth_mysql.php
index 213c4a852..46e175c17 100644
--- a/inc/auth_mysql.php
+++ b/inc/auth_mysql.php
@@ -1,14 +1,21 @@
 <?php
 /**
- * This is used to authenticate against an MySQL server
+ * MySQL authentication backend
  *
- * PHPs MySQL extension is needed
+ * PHP's MySQL extension is needed
+ *
+ * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
+ * @author     Andreas Gohr <andi@splitbrain.org>
  */
 
 /**
+ * Execute SQL
+ *
  * Executes SQL statements and returns the results as list
  * of hashes. Returns false on error. Returns auto_increment
  * IDs on INSERT statements.
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function auth_mysql_runsql($sql_string) {
   global $conf;
@@ -41,9 +48,13 @@ function auth_mysql_runsql($sql_string) {
 }
 
 /**
- * required auth function
+ * Check user+password [required auth function]
  *
- * Checks if a user with the given password exists
+ * Checks if the given user exists and the given
+ * plaintext password is correct
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ * @return  bool
  */
 function auth_checkPass($user,$pass){
   global $conf;
@@ -56,7 +67,7 @@ function auth_checkPass($user,$pass){
 }
 
 /**
- * Required auth function
+ * Return user info [required auth function]
  *
  * Returns info about the given user needs to contain
  * at least these fields:
@@ -65,6 +76,7 @@ function auth_checkPass($user,$pass){
  * mail string  email addres of the user
  * grps array   list of groups the user is in
  *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function auth_getUserData($user){
   global $conf;
@@ -86,9 +98,11 @@ function auth_getUserData($user){
 }
 
 /**
- * Required auth function
+ * Create a new User [required auth function]
  *
  * Not implemented
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function auth_createUser($user,$name,$mail){
   msg("Sorry. Creating users is not supported by the MySQL backend, yet",-1);
diff --git a/inc/auth_plain.php b/inc/auth_plain.php
index 2b45b94ca..4213b8dcc 100644
--- a/inc/auth_plain.php
+++ b/inc/auth_plain.php
@@ -1,21 +1,28 @@
 <?php
-
 /**
+ * Plaintext authentication backend
+ *
  * If you want to authenticate against something
  * else then the builtin flatfile auth system
  * you have to reimplement the "required auth
  * functions"
+ *
+ * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
+ * @author     Andreas Gohr <andi@splitbrain.org>
  */
 
 
 /**
- * required auth function
+ * Check user+password [required auth function]
  *
  * Checks if the given user exists and the given
  * plaintext password is correct
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ * @return  bool
  */
 function auth_checkPass($user,$pass){
-  $users = auth_loadUserData();
+  $users = auth_plain_loadUserData();
   $pass = md5($pass); //encode pass
 
   if($users[$user]['pass'] == $pass){
@@ -26,7 +33,7 @@ function auth_checkPass($user,$pass){
 }
 
 /**
- * Required auth function
+ * Return user info [required auth function]
  *
  * Returns info about the given user needs to contain
  * at least these fields:
@@ -34,16 +41,16 @@ function auth_checkPass($user,$pass){
  * name string  full name of the user
  * mail string  email addres of the user
  * grps array   list of groups the user is in
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function auth_getUserData($user){
-  $users = auth_loadUserData();
+  $users = auth_plain_loadUserData();
   return $users[$user];
 }
 
 /**
- * Required auth function
- *
- * Creates a new user.
+ * Create a new User [required auth function]
  *
  * Returns false if the user already exists, null when an error
  * occured and the cleartext password of the new user if
@@ -51,11 +58,13 @@ function auth_getUserData($user){
  * 
  * The new user HAS TO be added to the default group by this
  * function!
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function auth_createUser($user,$name,$mail){
   global $conf;
 
-  $users = auth_loadUserData();
+  $users = auth_plain_loadUserData();
   if(isset($users[$user])) return false;
 
   $pass = auth_pwgen();
@@ -76,10 +85,14 @@ function auth_createUser($user,$name,$mail){
 }
 
 /**
- * used by the plaintext auth functions
+ * Load all user data
+ *
+ * Used by the plaintext auth functions
  * loads the user file into a datastructure
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
-function auth_loadUserData(){
+function auth_plain_loadUserData(){
   $data = array();
   $lines = file('conf/users.auth');
   foreach($lines as $line){
diff --git a/inc/common.php b/inc/common.php
index c64d08898..5098b76de 100644
--- a/inc/common.php
+++ b/inc/common.php
@@ -1,29 +1,46 @@
 <?
-require_once("conf/dokuwiki.php");
-require_once("inc/io.php");
+/**
+ * Common DokuWiki functions
+ *
+ * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
+ * @author     Andreas Gohr <andi@splitbrain.org>
+ */
 
-//set up error reporting to sane values
-error_reporting(E_ALL ^ E_NOTICE);
+  require_once("conf/dokuwiki.php");
+  require_once("inc/io.php");
 
-//make session rewrites XHTML compliant
-ini_set('arg_separator.output', '&amp;');
+  //set up error reporting to sane values
+  error_reporting(E_ALL ^ E_NOTICE);
 
-//init session
-session_name("DokuWiki");
-session_start();
+  //make session rewrites XHTML compliant
+  ini_set('arg_separator.output', '&amp;');
 
-//kill magic quotes
-if (get_magic_quotes_gpc()) {
-  if (!empty($_GET))    remove_magic_quotes($_GET);
-  if (!empty($_POST))   remove_magic_quotes($_POST);
-  if (!empty($_COOKIE)) remove_magic_quotes($_COOKIE);
-  if (!empty($_REQUEST)) remove_magic_quotes($_REQUEST);
-  if (!empty($_SESSION)) remove_magic_quotes($_SESSION);
-  ini_set('magic_quotes_gpc', 0);
-}
-set_magic_quotes_runtime(0);
-ini_set('magic_quotes_sybase',0);
+  //init session
+  session_name("DokuWiki");
+  session_start();
+
+  //kill magic quotes
+  if (get_magic_quotes_gpc()) {
+    if (!empty($_GET))    remove_magic_quotes($_GET);
+    if (!empty($_POST))   remove_magic_quotes($_POST);
+    if (!empty($_COOKIE)) remove_magic_quotes($_COOKIE);
+    if (!empty($_REQUEST)) remove_magic_quotes($_REQUEST);
+    if (!empty($_SESSION)) remove_magic_quotes($_SESSION);
+    ini_set('magic_quotes_gpc', 0);
+  }
+  set_magic_quotes_runtime(0);
+  ini_set('magic_quotes_sybase',0);
+
+  //disable gzip if not available
+  if($conf['usegzip'] && !function_exists('gzopen')){
+    $conf['usegzip'] = 0;
+  }
 
+/**
+ * remove magic quotes recursivly
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function remove_magic_quotes(&$array) {
   foreach (array_keys($array) as $key) {
     if (is_array($array[$key])) {
@@ -34,16 +51,11 @@ function remove_magic_quotes(&$array) {
   } 
 } 
 
-//disable gzip if not available
-if($conf['usegzip'] && !function_exists('gzopen')){
-  $conf['usegzip'] = 0;
-}
-
-/* ---------------------------------------------------------------------------------- */
-
 /**
- * This returns the full absolute URL to the directory where
+ * Returns the full absolute URL to the directory where
  * DokuWiki is installed in (includes a trailing slash)
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function getBaseURL($abs=false){
   global $conf;
@@ -83,8 +95,10 @@ function getBaseURL($abs=false){
 }
 
 /**
- * Returns info about the current document as associative
+ * Return info about the current document as associative
  * array.
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function pageinfo(){
   global $ID;
@@ -134,6 +148,8 @@ function pageinfo(){
  * -1 error
  *  0 info
  *  1 success
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function msg($message,$lvl=0){
   global $MSG;
@@ -146,7 +162,9 @@ function msg($message,$lvl=0){
 }
 
 /**
- * This builds the breadcrumbstrail and returns it as array
+ * This builds the breadcrumb trail and returns it as array
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function breadcrumbs(){
   global $ID;
@@ -181,9 +199,13 @@ function breadcrumbs(){
 }
 
 /**
+ * Filter for page IDs
+ *
  * This is run on a ID before it is outputted somewhere
  * currently used to replace the colon with something else
  * on Windows systems and to have proper URL encoding
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function idfilter($id){
   global $conf;
@@ -201,6 +223,8 @@ function idfilter($id){
 
 /**
  * This builds a link to a wikipage (using getBaseURL)
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function wl($id='',$more='',$script='doku.php',$canonical=false){
   global $conf;
@@ -223,6 +247,8 @@ function wl($id='',$more='',$script='doku.php',$canonical=false){
 
 /**
  * Just builds a link to a script
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function script($script='doku.php'){
   $link = getBaseURL();
@@ -232,6 +258,8 @@ function script($script='doku.php'){
 
 /**
  * Return namespacepart of a wiki ID
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function getNS($id){
  if(strpos($id,':')!==false){
@@ -241,15 +269,21 @@ function getNS($id){
 }
 
 /**
- * Returns the id without the namespace
+ * Returns the ID without the namespace
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function noNS($id){
   return preg_replace('/.*:/','',$id);
 }
 
 /**
+ * Spamcheck against wordlist
+ *
  * Checks the wikitext against a list of blocked expressions
  * returns true if the text contains any bad words
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function checkwordblock(){
   global $TEXT;
@@ -271,8 +305,11 @@ function checkwordblock(){
 }
 
 /**
- * Returns the IP of the client including X-Forwarded-For
- * Proxy Headers
+ * Return the IP of the client
+ *
+ * Honours X-Forwarded-For Proxy Headers
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function clientIP(){
   $my = $_SERVER['REMOTE_ADDR'];
@@ -283,8 +320,11 @@ function clientIP(){
 }
 
 /**
- * Checks if a given page is currently locked by anyone for editing.
+ * Checks if a given page is currently locked.
+ *
  * removes stale lockfiles
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function checklock($id){
   global $conf;
@@ -309,7 +349,9 @@ function checklock($id){
 }
 
 /**
- * Locks a page for editing
+ * Lock a page for editing
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function lock($id){
   $lock = wikiFN($id).'.lock';
@@ -321,9 +363,10 @@ function lock($id){
 }
 
 /**
- * Unlocks a page if it was locked by the user
+ * Unlock a page if it was locked by the user
  *
- * return true if a lock was removed
+ * @author Andreas Gohr <andi@splitbrain.org>
+ * @return bool true if a lock was removed
  */
 function unlock($id){
   $lock = wikiFN($id).'.lock';
@@ -338,8 +381,12 @@ function unlock($id){
 }
 
 /**
+ * Remove unwanted chars from ID
+ *
  * Cleans a given ID to only use allowed characters. Accented characters are
  * converted to unaccented ones
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function cleanID($id){
   global $conf;
@@ -382,6 +429,8 @@ function cleanID($id){
 /**
  * returns the full path to the datafile specified by ID and
  * optional revision
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function wikiFN($id,$rev=''){
   global $conf;
@@ -403,6 +452,8 @@ function wikiFN($id,$rev=''){
 /**
  * Returns the full filepath to a localized textfile if local
  * version isn't found the english one is returned
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function localeFN($id){
   global $conf;
@@ -417,7 +468,8 @@ function localeFN($id){
 /**
  * convert line ending to unix format
  *
- * @see: formText() for 2crlf conversion
+ * @see    formText() for 2crlf conversion
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function cleanText($text){
   $text = preg_replace("/(\015\012)|(\015)/","\012",$text);
@@ -429,7 +481,8 @@ function cleanText($text){
  * It also converts line endings to Windows format which is
  * pseudo standard for webforms. 
  *
- * @see: cleanText() for 2unix conversion
+ * @see    cleanText() for 2unix conversion
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function formText($text){
   $text = preg_replace("/\012/","\015\012",$text);
@@ -437,7 +490,9 @@ function formText($text){
 }
 
 /**
- * Returns the specified textfile in parsed format
+ * Returns the specified local text in parsed format
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function parsedLocale($id){
   //disable section editing
@@ -452,7 +507,9 @@ function parsedLocale($id){
 }
 
 /**
- * Returns the specified textfile in parsed format
+ * Returns the specified local text in raw format
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function rawLocale($id){
   return io_readFile(localeFN($id));
@@ -460,8 +517,12 @@ function rawLocale($id){
 
 
 /**
- * Returns the parsed Wikitext for the given id and revision. If $excuse
- * is true an explanation is returned if the file wasn't found
+ * Returns the parsed Wikitext for the given id and revision.
+ *
+ * If $excuse is true an explanation is returned if the file
+ * wasn't found
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function parsedWiki($id,$rev='',$excuse=true){
   $file = wikiFN($id,$rev);
@@ -489,15 +550,21 @@ function parsedWiki($id,$rev='',$excuse=true){
 
 /**
  * Returns the raw WikiText
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function rawWiki($id,$rev=''){
   return io_readFile(wikiFN($id,$rev));
 }
 
 /**
- * Returns the raw Wiki Text in three slices. The range parameter
- * Need to have the form "from-to" and gives the range of the section.
+ * Returns the raw Wiki Text in three slices.
+ *
+ * The range parameter needs to have the form "from-to"
+ * and gives the range of the section.
  * The returned order is prefix, section and suffix.
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function rawWikiSlices($range,$id,$rev=''){
   list($from,$to) = split('-',$range,2);
@@ -514,9 +581,13 @@ function rawWikiSlices($range,$id,$rev=''){
 }
 
 /**
+ * Joins wiki text slices
+ *
  * function to join the text slices with correct lineendings again.
  * When the pretty parameter is set to true it adds additional empty
  * lines between sections if needed (used on saving).
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function con($pre,$text,$suf,$pretty=false){
 
@@ -531,7 +602,11 @@ function con($pre,$text,$suf,$pretty=false){
 }
 
 /**
+ * print debug messages
+ *
  * little function to print the content of a var
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function dbg($msg,$hidden=false){
   (!$hidden) ? print '<pre class="dbg">' : print "<!--\n";
@@ -541,6 +616,8 @@ function dbg($msg,$hidden=false){
 
 /**
  * Add's an entry to the changelog
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function addLogEntry($id,$summary=""){
   global $conf;
@@ -561,6 +638,8 @@ function addLogEntry($id,$summary=""){
 /**
  * returns an array of recently changed files using the
  * changelog
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function getRecents($num=0,$incdel=false){
   global $conf;
@@ -594,6 +673,8 @@ function getRecents($num=0,$incdel=false){
 
 /**
  * Saves a wikitext by calling io_saveFile
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function saveWikiText($id,$text,$summary){
   global $conf;
@@ -630,6 +711,8 @@ function saveWikiText($id,$text,$summary){
 /**
  * moves the current version to the attic and returns its
  * revision date
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function saveOldRevision($id){
 	global $conf;
@@ -650,6 +733,8 @@ function saveOldRevision($id){
 /**
  * Sends a notify mail to the wikiadmin when a page was
  * changed
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function notify($id,$rev="",$summary=""){
   global $lang;
@@ -687,6 +772,11 @@ function notify($id,$rev="",$summary=""){
   @mail($conf['notify'],$subject,$text,$hdrs);
 }
 
+/**
+ * Return a list of available page revisons
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function getRevisions($id){
   $revd = dirname(wikiFN($id,'foo'));
   $revs = array();
@@ -708,6 +798,8 @@ function getRevisions($id){
 
 /**
  * downloads a file from the net and saves it to the given location
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function download($url,$file){
   $fp = @fopen($url,"rb");
@@ -727,6 +819,8 @@ function download($url,$file){
 
 /**
  * extracts the query from a google referer
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function getGoogleQuery(){
   $url = parse_url($_SERVER['HTTP_REFERER']);
@@ -739,8 +833,9 @@ function getGoogleQuery(){
 }
 
 /**
- * This function tries the locales given in the
- * language file
+ * Try to set correct locale
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function setCorrectLocale(){
   global $conf;
@@ -758,14 +853,14 @@ function setCorrectLocale(){
 }
 
 /**
-* Return the human readable size of a file
-*
-* @param       int    $size   A file size
-* @param       int    $dec    A number of decimal places
-* @author      Martin Benjamin <b.martin@cybernet.ch>
-* @author      Aidan Lister <aidan@php.net>
-* @version     1.0.0
-*/
+ * Return the human readable size of a file
+ *
+ * @param       int    $size   A file size
+ * @param       int    $dec    A number of decimal places
+ * @author      Martin Benjamin <b.martin@cybernet.ch>
+ * @author      Aidan Lister <aidan@php.net>
+ * @version     1.0.0
+ */
 function filesize_h($size, $dec = 1)
 {
   $sizes = array('B', 'KB', 'MB', 'GB');
@@ -780,6 +875,11 @@ function filesize_h($size, $dec = 1)
   return round($size, $dec) . ' ' . $sizes[$i];
 }
 
+/**
+ * Run a few sanity checks
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function check(){
   global $conf;
   global $INFO;
diff --git a/inc/feedcreator.class.php b/inc/feedcreator.class.php
index dbd1edc95..00731ef74 100644
--- a/inc/feedcreator.class.php
+++ b/inc/feedcreator.class.php
@@ -1534,7 +1534,7 @@ echo $rss->saveFeed("RSS0.91", "feed.xml");
 /**
  * This class allows to override the hardcoded charset
  *
- * @author Andreas Gohr
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 class DokuWikiFeedCreator extends UniversalFeedCreator{
   function createFeed($format = "RSS0.91",$encoding='iso-8859-15') {
diff --git a/inc/format.php b/inc/format.php
index 68f15fe12..572107a87 100644
--- a/inc/format.php
+++ b/inc/format.php
@@ -1,11 +1,20 @@
 <?
-require_once("conf/dokuwiki.php");
-require_once("inc/common.php");
+/**
+ * link format functions
+ *
+ * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
+ * @author     Andreas Gohr <andi@splitbrain.org>
+ */
+
+  require_once("conf/dokuwiki.php");
+  require_once("inc/common.php");
 
 
 /**
  * Assembles all parts defined by the link formater below
  * Returns HTML for the link
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function format_link_build($link){
   //make sure the url is XHTML compliant
@@ -44,6 +53,11 @@ function format_link_build($link){
  *
  */
 
+/**
+ * format wiki links
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function format_link_wiki($link){
   global $conf;
   global $ID; //we use this to get the current namespace
@@ -112,6 +126,11 @@ function format_link_wiki($link){
   return $link;
 }
 
+/**
+ * format external URLs
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function format_link_externalurl($link){
   global $conf;
   //simple setup
@@ -128,7 +147,13 @@ function format_link_externalurl($link){
   return $link;
 }
 
-//this only works in IE :-(
+/**
+ * format windows share links
+ *
+ * this only works in IE :-(
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function format_link_windows($link){
   global $conf;
   global $lang;
@@ -149,6 +174,11 @@ function format_link_windows($link){
   return $link;
 }
 
+/**
+ * format email addresses
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function format_link_email($link){
   global $conf;
   //simple setup
@@ -181,6 +211,11 @@ function format_link_email($link){
   return $link;
 }
 
+/**
+ * format interwiki links
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function format_link_interwiki($link){
   global $conf;
 
@@ -252,7 +287,11 @@ function format_link_interwiki($link){
   return $link;
 }
 
-
+/**
+ * format embedded media
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function format_link_media($link){
   global $conf;
 
@@ -321,7 +360,11 @@ function format_link_media($link){
 }
 
 /**
- * Builds an URL list from a RSS feed
+ * Build an URL list from a RSS feed
+ *
+ * Uses magpie
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function format_rss($url){
   global $lang;
@@ -355,7 +398,11 @@ function format_rss($url){
   return $ret;
 }
 
-
+/**
+ * Create cache images
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function img_cache(&$csrc,&$src,&$w,&$h,$nocache){
   global $conf;
   
@@ -427,6 +474,11 @@ function img_cache(&$csrc,&$src,&$w,&$h,$nocache){
   return $isimg;
 }
 
+/**
+ * resize images
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function img_resize($ext,$from,$from_w,$from_h,$to,$to_w,$to_h){
   // create cachedir
   io_makeFileDir($to);
diff --git a/inc/html.php b/inc/html.php
index 157291af4..1ab53ac64 100644
--- a/inc/html.php
+++ b/inc/html.php
@@ -1,8 +1,17 @@
 <?
-include_once("inc/format.php");
+/**
+ * HTML output functions
+ *
+ * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
+ * @author     Andreas Gohr <andi@splitbrain.org>
+ */
+
+  include_once("inc/format.php");
 
 /**
  * Convenience function to quickly build a wikilink
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_wikilink($url,$name='',$search=''){
   global $conf;
@@ -21,6 +30,8 @@ function html_wikilink($url,$name='',$search=''){
 
 /**
  * The loginform
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_login(){
   global $lang;
@@ -67,6 +78,8 @@ function html_login(){
 
 /**
  * shows the edit/source/show button dependent on current mode
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_editbutton(){
   global $ID;
@@ -90,6 +103,11 @@ function html_editbutton(){
   return $r;
 }
 
+/**
+ * prints a section editing button
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function html_secedit_button($section,$p){
   global $ID;
   global $lang;
@@ -105,6 +123,11 @@ function html_secedit_button($section,$p){
   return $secedit;
 }
 
+/**
+ * inserts section edit buttons if wanted or removes the markers
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function html_secedit($text,$show=true){
   global $INFO;
   if($INFO['writable'] && $show){
@@ -122,6 +145,8 @@ function html_secedit($text,$show=true){
 
 /**
  * displays the breadcrumbs trace
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_breadcrumbs(){
   global $lang;
@@ -142,6 +167,8 @@ function html_breadcrumbs(){
 
 /**
  * display the HTML head and metadata
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_head(){
   global $ID;
@@ -203,6 +230,8 @@ function html_head(){
 
 /**
  * Displays a button (using it's own form)
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_btn($name,$id,$akey,$params,$method='get'){
   global $conf;
@@ -245,6 +274,8 @@ function html_btn($name,$id,$akey,$params,$method='get'){
 
 /**
  * Check for the given permission or prints an error
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_acl($perm){
   global $INFO;
@@ -256,6 +287,8 @@ function html_acl($perm){
 
 /**
  * Displays the page header and calls html_head()
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_header(){
   global $ID;
@@ -307,8 +340,12 @@ function html_header(){
 }
 
 /**
+ * display document and user info
+ *
  * Displays some Metadata like who's logged in and the last modified
  * date - do not confuse this with the HTML meta header.
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_metainfo(){
   global $conf;
@@ -349,6 +386,11 @@ function html_metainfo(){
   print '</div>';
 }
 
+/**
+ * Diplay the overall footer
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function html_footer(){
   global $ID;
   global $REV;
@@ -391,6 +433,11 @@ function html_footer(){
 <?
 }
 
+/**
+ * Print the table of contents
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function html_toc($toc){
   global $lang;
   $ret  = '';
@@ -409,7 +456,11 @@ function html_toc($toc){
 }
 
 /**
+ * TOC item formatter
+ *
  * User function for html_buildlist()
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_list_toc($item){
   $ret  = '';
@@ -419,6 +470,11 @@ function html_list_toc($item){
   return $ret;
 }
 
+/**
+ * show a wiki page
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function html_show($text=''){
   global $ID;
   global $REV;
@@ -445,6 +501,8 @@ function html_show($text=''){
 
 /**
  * Highlights searchqueries in HTML code
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_hilight($html,$query){
   $queries = preg_split ("/\s/",$query,-1,PREG_SPLIT_NO_EMPTY);
@@ -456,7 +514,9 @@ function html_hilight($html,$query){
 }
 
 /**
- * This function runs a search and displays the result
+ * Run a search and display the result
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_search(){
   require_once("inc/search.php");
@@ -503,6 +563,11 @@ function html_search(){
   }
 }
 
+/**
+ * Display error on locked pages
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function html_locked($ip){
   global $ID;
   global $conf;
@@ -519,6 +584,11 @@ function html_locked($ip){
   print '</ul>';
 }
 
+/**
+ * list old revisions
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function html_revisions(){
   global $ID;
   global $INFO;
@@ -543,6 +613,11 @@ function html_revisions(){
   print '</ul>';
 }
 
+/**
+ * display recent changes
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function html_recent(){
   global $conf;
   $recents = getRecents(0,true);
@@ -563,6 +638,11 @@ function html_recent(){
   print '</ul>';
 }
 
+/**
+ * Display page index
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function html_index($ns){
   require_once("inc/search.php");
   global $conf;
@@ -583,7 +663,11 @@ function html_index($ns){
 }
 
 /**
+ * Index item formatter
+ *
  * User function for html_buildlist()
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_list_index($item){
   $ret = '';
@@ -600,10 +684,14 @@ function html_list_index($item){
 }
 
 /**
+ * Build an unordered list
+ *
  * Build an unordered list from the given $data array
  * Each item in the array has to have a 'level' property
  * the item itself gets printed by the given $func user
  * function
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_buildlist($data,$class,$func){
   $level = 0;
@@ -645,6 +733,11 @@ function html_buildlist($data,$class,$func){
   return $ret;
 }
 
+/**
+ * display backlinks
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function html_backlinks(){
   require_once("inc/search.php");
   global $ID;
@@ -673,6 +766,11 @@ function html_backlinks(){
   print '</ul>';
 }
 
+/**
+ * show diff
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function html_diff($text='',$intro=true){
   require_once("inc/DifferenceEngine.php");
   global $ID;
@@ -712,6 +810,11 @@ function html_diff($text='',$intro=true){
   <?
 }
 
+/**
+ * show warning on conflict detection
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ */
 function html_conflict($text,$summary){
   global $ID;
   global $lang;
@@ -733,7 +836,9 @@ function html_conflict($text,$summary){
 }
 
 /**
- * Prints the glovbal message array
+ * Prints the global message array
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_msgarea(){
   global $MSG;
@@ -749,6 +854,8 @@ function html_msgarea(){
 
 /**
  * Prints the registration form
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_register(){
   global $lang;
@@ -783,6 +890,8 @@ function html_register(){
 
 /**
  * This displays the edit form (lots of logic included)
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_edit($text=null,$include='edit'){ //FIXME: include needed?
   global $ID;
@@ -909,6 +1018,8 @@ function html_edit($text=null,$include='edit'){ //FIXME: include needed?
 
 /**
  * prepares the signature string as configured in the config
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_signature(){
   global $conf;
@@ -925,6 +1036,8 @@ function html_signature(){
 
 /**
  * prints some debug info
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function html_debug(){
   global $conf;
diff --git a/inc/io.php b/inc/io.php
index c84604a43..dfdbc4e1c 100644
--- a/inc/io.php
+++ b/inc/io.php
@@ -1,13 +1,19 @@
 <?
-require_once("inc/common.php");
-require_once("inc/parser.php");
-
-
+/**
+ * File IO functions
+ *
+ * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
+ * @author     Andreas Gohr <andi@splitbrain.org>
+ */
 
+  require_once("inc/common.php");
+  require_once("inc/parser.php");
 
 /**
  * Returns the parsed text from the given sourcefile. Uses cache
  * if exists. Creates it if not.
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function io_cacheParse($file){
   global $conf;
@@ -50,8 +56,11 @@ function io_cacheParse($file){
 }
 
 /**
- * Returns content of $file as cleaned string. Uses gzip if extension
- * is .gz
+ * Returns content of $file as cleaned string.
+ *
+ * Uses gzip if extension is .gz
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function io_readFile($file){
   $ret = '';
@@ -66,10 +75,12 @@ function io_readFile($file){
 }
 
 /**
- * Saves $content to $file. Uses gzip if extension
- * is .gz
+ * Saves $content to $file.
+ *
+ * Uses gzip if extension is .gz
  *
- * returns true on success
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ * @return bool true on success
  */
 function io_saveFile($file,$content){
   io_makeFileDir($file);
@@ -95,6 +106,8 @@ function io_saveFile($file,$content){
 
 /**
  * Create the directory needed for the given file
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function io_makeFileDir($file){
   global $conf;
@@ -110,7 +123,7 @@ function io_makeFileDir($file){
 /**
  * Creates a directory hierachy.
  *
- * @see    http://www.php.net/manual/en/function.mkdir.php
+ * @link    http://www.php.net/manual/en/function.mkdir.php
  * @author <saint@corenova.com>
  */
 function io_mkdir_p($target){
@@ -123,7 +136,9 @@ function io_mkdir_p($target){
 
 /**
  * Runs an external command and returns it's output as string
- * inspired by a patch by Harry Brueckner <harry_b@eml.cc>
+ *
+ * @author Harry Brueckner <harry_b@eml.cc>
+ * @author Andreas Gohr <andi@splitbrain.org>
  */
 function io_runcmd($cmd){
   $fh = popen($cmd, "r");
diff --git a/inc/parser.php b/inc/parser.php
index 5b8a1323e..556533af6 100644
--- a/inc/parser.php
+++ b/inc/parser.php
@@ -1,14 +1,24 @@
 <?
-include_once("inc/common.php");
-include_once("inc/html.php");
-include_once("inc/format.php");
-require_once("lang/en/lang.php");
-require_once("lang/".$conf['lang']."/lang.php");
+/**
+ * The DokuWiki parser
+ *
+ * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
+ * @author     Andreas Gohr <andi@splitbrain.org>
+ */
+
+  include_once("inc/common.php");
+  include_once("inc/html.php");
+  include_once("inc/format.php");
+  require_once("lang/en/lang.php");
+  require_once("lang/".$conf['lang']."/lang.php");
 
 /**
- * The main parser function. Accepts raw data and returns
- * valid xhtml
-*/  
+ * The main parser function.
+ *
+ * Accepts raw data and returns valid xhtml
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ */  
 function parse($text){
   global $parser;
   global $conf;
@@ -119,10 +129,14 @@ function parse($text){
 }
 
 /**
+ * Line by line preparser
+ *
  * This preparses the text by walking it line by line. This
  * is the only place where linenumbers are still available (needed
  * for section edit. Some precautions have to be taken to not change
  * any noparse block.
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function preparse($text,&$table,&$hltable){
   $lines = split("\n",$text);
@@ -191,9 +205,13 @@ function preparse($text,&$table,&$hltable){
 }
 
 /**
+ * Build TOC lookuptable
+ *
  * This function adds some information about the given headline
  * to a lookuptable to be processed later. Returns a unique token
  * that idetifies the headline later
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function tokenize_headline(&$hltable,$pre,$hline,$lno){
   switch (strlen($pre)){
@@ -221,6 +239,11 @@ function tokenize_headline(&$hltable,$pre,$hline,$lno){
   return $token;
 }
 
+/**
+ * Headline formatter
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ */
 function format_headlines(&$table,&$hltable,&$text){
   global $parser;
   global $conf;
@@ -295,6 +318,8 @@ function format_headlines(&$table,&$hltable,&$text){
 
 /**
  * Formats various link types using the functions from format.php
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function linkformat($match){
   global $conf;
@@ -346,6 +371,8 @@ function linkformat($match){
 
 /**
  * Simple text formating and typography is done here
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function simpleformat($text){
   global $conf;
@@ -409,7 +436,9 @@ function simpleformat($text){
 }
 
 /**
- * Does the footnote formating
+ * Footnote formating
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function footnotes($text){
   $num = 0;
@@ -429,7 +458,9 @@ function footnotes($text){
 }
 
 /**
- * Replaces smileys with their graphic equivalents
+ * Replace smileys with their graphic equivalents
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function smileys(&$table,&$text){
   $smileys = file('conf/smileys.conf');
@@ -445,7 +476,9 @@ function smileys(&$table,&$text){
 }
 
 /**
- * Adds acronym tags to known acronyms
+ * Add acronym tags to known acronyms
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function acronyms(&$table,&$text){
   $acronyms = file('conf/acronyms.conf');
@@ -459,9 +492,10 @@ function acronyms(&$table,&$text){
   }
 } 
 
-
 /**
- * Applies custom text replacements
+ * Apply custom text replacements
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function customs($text){
   $reps = file ('conf/custom.conf');
@@ -477,6 +511,11 @@ function customs($text){
   return $text;
 }
 
+/**
+ * Replace regexp with token
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ */
 function firstpass(&$table,&$text,$regexp,$replace,$lpad='',$rpad=''){
   //extended regexps have to be disabled for inserting the token
   //and later reenabled when handling the actual code:
@@ -494,6 +533,11 @@ function firstpass(&$table,&$text,$regexp,$replace,$lpad='',$rpad=''){
   }
 }
 
+/**
+ * create a random and hopefully unique token
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ */
 function mkToken(){
   return '~'.md5(uniqid(rand(), true)).'~';
 }
@@ -501,7 +545,7 @@ function mkToken(){
 /**
  * Do quote blocks
  *
- * FIXME fix paragraphs
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function quoteformat($block){
   $block = trim($block);
@@ -548,6 +592,11 @@ function quoteformat($block){
   return "$ret";
 }
 
+/**
+ * format inline tables
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ */
 function tableformat($block) {
   $block = trim($block);
   $lines = split("\n",$block);
@@ -608,6 +657,11 @@ function tableformat($block) {
   return $ret;
 }
 
+/**
+ * format lists
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ */
 function listformat($block){
   //remove 1st newline 
   $block = substr($block,1);
@@ -686,6 +740,13 @@ function listformat($block){
   return "</p>\n".$ret."\n<p>";
 }
 
+/**
+ * Handle preformatted blocks
+ *
+ * Uses GeSHi for syntax highlighting
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ */
 function preformat($text,$type,$option=''){
   global $conf;
   //unescape
@@ -742,6 +803,11 @@ function preformat($text,$type,$option=''){
   return $text;
 }
 
+/**
+ * Format embedded media (images)
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
+ */
 function mediaformat($text){
   global $conf;
 
diff --git a/inc/search.php b/inc/search.php
index bb941a3f3..c620b7133 100644
--- a/inc/search.php
+++ b/inc/search.php
@@ -1,10 +1,20 @@
 <?
+/**
+ * DokuWiki search functions
+ *
+ * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
+ * @author     Andreas Gohr <andi@splitbrain.org>
+ */
 
-require_once("inc/common.php");
+  require_once("inc/common.php");
 
 /**
+ * recurse direcory
+ *
  * This function recurses into a given base directory
  * and calls the supplied function for each file and directory
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function search(&$data,$base,$func,$opts,$dir='',$lvl=1){
   $dirs   = array();
@@ -60,9 +70,11 @@ function search(&$data,$base,$func,$opts,$dir='',$lvl=1){
  */
 
 /**
- * This function build the browsable index of pages
+ * Build the browsable index of pages
  *
  * $opts['ns'] is the current namespace
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function search_index(&$data,$base,$file,$type,$lvl,$opts){
   $return = true;
@@ -88,7 +100,9 @@ function search_index(&$data,$base,$file,$type,$lvl,$opts){
 }
 
 /**
- * This function lists all namespaces
+ * List all namespaces
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function search_namespaces(&$data,$base,$file,$type,$lvl,$opts){
   if($type == 'f') return true; //nothing to do on files
@@ -101,7 +115,9 @@ function search_namespaces(&$data,$base,$file,$type,$lvl,$opts){
 }
 
 /**
- * This function lists all mediafiles in a namespace
+ * List all mediafiles in a namespace
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function search_media(&$data,$base,$file,$type,$lvl,$opts){
   //we do nothing with directories
@@ -130,6 +146,8 @@ function search_media(&$data,$base,$file,$type,$lvl,$opts){
 
 /**
  * This function just lists documents (for RSS namespace export)
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function search_list(&$data,$base,$file,$type,$lvl,$opts){
   //we do nothing with directories
@@ -149,6 +167,8 @@ function search_list(&$data,$base,$file,$type,$lvl,$opts){
  * Quicksearch for searching matching pagenames
  *
  * $opts['query'] is the search query
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function search_pagename(&$data,$base,$file,$type,$lvl,$opts){
   //we do nothing with directories
@@ -174,6 +194,8 @@ function search_pagename(&$data,$base,$file,$type,$lvl,$opts){
  *
  * $opts['ns']    namespace of the page
  * $opts['name']  name of the page without namespace
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function search_backlinks(&$data,$base,$file,$type,$lvl,$opts){
   //we do nothing with directories
@@ -227,6 +249,8 @@ function search_backlinks(&$data,$base,$file,$type,$lvl,$opts){
  * Fulltextsearch
  *
  * $opts['query'] is the search query
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function search_fulltext(&$data,$base,$file,$type,$lvl,$opts){
   //we do nothing with directories
@@ -274,8 +298,12 @@ function search_fulltext(&$data,$base,$file,$type,$lvl,$opts){
 }
 
 /**
+ * fulltext sort
+ *
  * Callback sort function for use with usort to sort the data
  * structure created by search_fulltext. Sorts descending by count
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function sort_search_fulltext($a,$b){
   if($a['count'] > $b['count']){
@@ -289,6 +317,8 @@ function sort_search_fulltext($a,$b){
 
 /**
  * translates a document path to an ID
+ *
+ * @author  Andreas Gohr <andi@splitbrain.org>
  */
 function pathID($path){
   $id = str_replace('/',':',$path);