From: garvinhicking <garvinhicking>
Date: Fri, 25 Nov 2005 17:07:00 +0000 (+0000)
Subject: Document code. Uff.
X-Git-Tag: 1.0~271
X-Git-Url: http://git.mjollnir.org/gw?a=commitdiff_plain;h=6498f679aec534e0f5551a979041d13b500059e1;p=s9y.git

Document code. Uff.
---

diff --git a/include/functions_config.inc.php b/include/functions_config.inc.php
index 3b1306e..aadec57 100644
--- a/include/functions_config.inc.php
+++ b/include/functions_config.inc.php
@@ -3,13 +3,15 @@
 # All rights reserved.  See LICENSE file for licensing details
 
 /**
- * SHORT
- *
- * LONG
+ * Adds a new author account
  *
  * @access public
- * @param
- * @return
+ * @param   string  New username
+ * @param   string  New password
+ * @param   string  The realname of the user
+ * @param   string  The email address of the user
+ * @param   int     The userlevel of a user
+ * @return  int     The new user ID of the added author
  */
 function serendipity_addAuthor($username, $password, $realname, $email, $userlevel=0) {
     global $serendipity;
@@ -35,13 +37,13 @@ function serendipity_addAuthor($username, $password, $realname, $email, $userlev
 }
 
 /**
- * SHORT
+ * Delete an author account
  *
- * LONG
+ * (Note, this function does not delete entries by an author)
  *
  * @access public
- * @param
- * @return
+ * @param   int     The author ID to delete
+ * @return  boolean     True on success, false on error or unsufficient privileges
  */
 function serendipity_deleteAuthor($authorid) {
     global $serendipity;
@@ -57,13 +59,14 @@ function serendipity_deleteAuthor($authorid) {
 }
 
 /**
- * SHORT
+ * Removes a configuration value from the Serendipity Configuration
  *
- * LONG
+ * Global config items have the authorid 0, author-specific configuration items have the corresponding authorid.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The name of the configuration value
+ * @param   int         The ID of the owner of the config value (0: global)
+ * @return null
  */
 function serendipity_remove_config_var($name, $authorid = 0) {
     global $serendipity;
@@ -71,13 +74,15 @@ function serendipity_remove_config_var($name, $authorid = 0) {
 }
 
 /**
- * SHORT
+ * Sets a configuration value for the Serendipity Configuration
  *
- * LONG
+ * Global config items have the authorid 0, author-specific configuration items have the corresponding authorid.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The name of the configuration value
+ * @param   string      The value of the configuration item
+ * @param   int         The ID of the owner of the config value (0: global)
+ * @return  null
  */
 function serendipity_set_config_var($name, $val, $authorid = 0) {
     global $serendipity;
@@ -99,13 +104,13 @@ function serendipity_set_config_var($name, $val, $authorid = 0) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Retrieve a global configuration value for a specific item of the current Serendipity Configuration
  *
  * @access public
- * @param
- * @return
+ * @param   string      The name of the configuration value
+ * @param   string      The default value of a configuration item, if not found in the Database
+ * @param   boolean     If set to true, the default value of a configuration item will be returned if the item is set, but empty. If false, an empty configuration value will be returned empty. This is required for getting default values if you do not want to store/allow empty config values.
+ * @return  string      The configuration value content
  */
 function serendipity_get_config_var($name, $defval = false, $empty = false) {
     global $serendipity;
@@ -121,13 +126,15 @@ function serendipity_get_config_var($name, $defval = false, $empty = false) {
 }
 
 /**
- * SHORT
+ * Retrieve an author-specific configuration value for an item of the Serendipity Configuration stored in the DB
  *
- * LONG
+ * Despite the serendipity_get_config_var() function, this will retrieve author-specific values straight from the Database.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The name of the configuration value
+ * @param   int         The ID of the owner of the config value (0: global)
+ * @param   string      The default value of a configuration option, if not set in the DB
+ * @return  string      The configuration value content
  */
 function serendipity_get_user_config_var($name, $authorid, $default = '') {
     global $serendipity;
@@ -147,13 +154,15 @@ function serendipity_get_user_config_var($name, $authorid, $default = '') {
 }
 
 /**
- * SHORT
+ * Retrieves an author-specific account value
  *
- * LONG
+ * This retrieves specific account data from the user configuration, not from the serendipity configuration.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The name of the configuration value
+ * @param   int         The ID of the author to fetch the configuration for
+ * @param   string      The default value of a configuration option, if not set in the DB
+ * @return  string      The configuration value content
  */
 function serendipity_get_user_var($name, $authorid, $default) {
     global $serendipity;
@@ -168,13 +177,16 @@ function serendipity_get_user_var($name, $authorid, $default) {
 }
 
 /**
- * SHORT
+ * Updates data from the author-specific account
  *
- * LONG
+ * This sets the personal account data of a serendipity user within the 'authors' DB table
  *
  * @access public
- * @param
- * @return
+ * @param   string      The name of the configuration value
+ * @param   string      The content of the configuration value
+ * @param   int         The ID of the author to set the configuration for
+ * @param   boolean     If set to true, the stored config value will be imported to the Session/current config of the user. This is applied for example when you change your own user's preferences and want it to be immediately reflected in the interface.
+ * @return null
  */
 function serendipity_set_user_var($name, $val, $authorid, $copy_to_s9y = true) {
     global $serendipity;
@@ -221,13 +233,15 @@ function serendipity_set_user_var($name, $val, $authorid, $copy_to_s9y = true) {
 }
 
 /**
- * SHORT
+ * Gets the full filename and path of a template/style/theme file
  *
- * LONG
+ * The returned full path is depending on the second parameter, where you can either fetch a HTTP path, or a realpath.
+ * The file is searched in the current template, and if it is not found there, it is returned from the default template.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The filename to search for in the selected template
+ * @param   string      The path selector that tells whether to return a HTTP or realpath
+ * @return  string      The full path+filename to the requested file
  */
 function serendipity_getTemplateFile($file, $key = 'serendipityHTTPPath') {
     global $serendipity;
@@ -252,13 +266,14 @@ function serendipity_getTemplateFile($file, $key = 'serendipityHTTPPath') {
 }
 
 /**
- * SHORT
+ * Loads all configuration values and imports them to the $serendipity array
  *
- * LONG
+ * This function may be called twice - once for the global config and once for
+ * user-specific config
  *
  * @access public
- * @param
- * @return
+ * @param   int     The Authorid to fetch the configuration from (0: global)
+ * @return  null
  */
 function serendipity_load_configuration($author = null) {
     global $serendipity;
@@ -284,13 +299,10 @@ function serendipity_load_configuration($author = null) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Perform logout functions (destroys session data)
  *
  * @access public
- * @param
- * @return
+ * @return null
  */
 function serendipity_logout() {
     $_SESSION['serendipityAuthedUser'] = false;
@@ -299,13 +311,11 @@ function serendipity_logout() {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Perform login to Serendipity
  *
  * @access public
- * @param
- * @return
+ * @param   boolean     If set to true, external plugins will be queried for getting a login
+ * @return  boolean     Return true, if the user is logged in. False if not.
  */
 function serendipity_login($use_external = true) {
     global $serendipity;
@@ -318,6 +328,7 @@ function serendipity_login($use_external = true) {
         return true;
     }
 
+    // First try login via POST data. If true, the userinformation will be stored in a cookie (optionally)
     if (serendipity_authenticate_author($serendipity['POST']['user'], $serendipity['POST']['pass'], false, $use_external)) {
         if (empty($serendipity['POST']['auto'])) {
             serendipity_deleteCookie('author_information');
@@ -328,6 +339,7 @@ function serendipity_login($use_external = true) {
             serendipity_setCookie('author_information', base64_encode($package));
             return true;
         }
+    // Now try login via COOKIE data
     } elseif ( isset($serendipity['COOKIE']['author_information']) ) {
         $cookie = unserialize(base64_decode($serendipity['COOKIE']['author_information']));
         if (serendipity_authenticate_author($cookie['username'], $cookie['password'], false, $use_external)) {
@@ -340,13 +352,10 @@ function serendipity_login($use_external = true) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Check if a user is logged in
  *
  * @access public
- * @param
- * @return
+ * @return boolean  TRUE when logged in, FALSE when not.
  */
 function serendipity_userLoggedIn() {
     if ($_SESSION['serendipityAuthedUser'] === true && IS_installed) {
@@ -357,13 +366,14 @@ function serendipity_userLoggedIn() {
 }
 
 /**
- * SHORT
+ * A clone of an ifsetor() function to set a variable conditional on if the target already exists
  *
- * LONG
+ * The function sets the contents of $source into the $target variable, but only if $target is not yet set. Eases up some if...else logic or multiple ternary operators
  *
  * @access public
- * @param
- * @return
+ * @param   mixed   Source variable that should be set into the target variable (reference call!)
+ * @param   mixed   Target variable, that should get the contents of the source variable (reference call!)
+ * @return  boolean True, when $target was not yet set and has been altered. False when no changes where made.
  */
 function serendipity_restoreVar(&$source, &$target) {
     global $serendipity;
@@ -377,13 +387,15 @@ function serendipity_restoreVar(&$source, &$target) {
 }
 
 /**
- * SHORT
+ * Echo Javascript code to set a cookie variable
  *
- * LONG
+ * This function is useful if your HTTP headers were already sent, but you still want to set a cookie
+ * Note that contents are echo'd, not return'd.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The name of the cookie variable
+ * @param   string      The contents of the cookie variable
+ * @return  null
  */
 function serendipity_JSsetCookie($name, $value) {
     $name  = str_replace('"', '\"', $name);
@@ -393,13 +405,12 @@ function serendipity_JSsetCookie($name, $value) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Set a Cookie via HTTP calls, and update $_COOKIE plus $serendipity['COOKIE'] array.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The name of the cookie variable
+ * @param   string      The contents of the cookie variable
+ * @return null
  */
 function serendipity_setCookie($name,$value) {
     global $serendipity;
@@ -410,12 +421,12 @@ function serendipity_setCookie($name,$value) {
 }
 
 /**
- * SHORT
+ * Deletes an existing cookie value
  *
  * LONG
  *
  * @access public
- * @param
+ * @param   string      Name of the cookie to delete
  * @return
  */
 function serendipity_deleteCookie($name) {
@@ -427,13 +438,18 @@ function serendipity_deleteCookie($name) {
 }
 
 /**
- * SHORT
+ * Perform user authentication routine
  *
- * LONG
+ * If a user is already authenticated via session data, this bypasses some routines.
+ * After a user has ben authenticated, several SESSION variables ar set.
+ * If the authentication fails, the session is destroyed.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The username to check
+ * @param   string      The password to check (may contain plaintext or MD5 hash)
+ * @param   boolean     Indicates whether the input password is already in MD5 format (TRUE) or not (FALSE).
+ * @param   boolean     Indicates whether to query external plugins for authentication
+ * @return  boolean     True on success, False on error
  */
 function serendipity_authenticate_author($username = '', $password = '', $is_md5 = false, $use_external = true) {
     global $serendipity;
@@ -484,13 +500,13 @@ function serendipity_authenticate_author($username = '', $password = '', $is_md5
 }
 
 /**
- * SHORT
+ * Performs a check whether an iframe for the admin section shall be emitted
  *
- * LONG
+ * The iframe is used for previewing an entry with the stylesheet of the frontend.
+ * It fetches its data from the session input data.
  *
- * @access public
- * @param
- * @return
+ * @access private
+ * @return boolean  True, if iframe was requested, false if not.
  */
 function serendipity_is_iframe() {
     global $serendipity;
@@ -538,13 +554,17 @@ function serendipity_is_iframe() {
 }
 
 /**
- * SHORT
+ * Prints the content of the iframe. 
  *
- * LONG
+ * Called by serendipity_is_iframe, when preview is requested. Fetches data from session.
+ * An iframe is used so that a single s9y page must not timeout on intensive operations,
+ * and so that the frontend stylesheet can be embedded without screwing up the backend.
  *
- * @access public
- * @param
- * @return
+ * @access private
+ * @see serendipity_is_iframe()
+ * @param   mixed   The entry array (comes from session variable)
+ * @param   string  Indicates whether an entry is previewed or saved. Save performs XML-RPC calls.
+ * @return  boolean Indicates whether iframe data was printed
  */
 function serendipity_iframe(&$entry, $mode = null) {
     global $serendipity;
@@ -590,13 +610,15 @@ function serendipity_iframe(&$entry, $mode = null) {
 }
 
 /**
- * SHORT
+ * Creates the necessary session data to be used by later iframe calls
  *
- * LONG
+ * This function emits the actual <iframe> call.
  *
- * @access public
- * @param
- * @return
+ * @access private
+ * @see serendipity_is_iframe()
+ * @param   string  Indicates whether an entry is previewed or saved. Save performs XML-RPC calls.
+ * @param   mixed   The entry array (comes from HTTP POST request)
+ * @return  boolean Indicates whether iframe data was stored
  */
 function serendipity_iframe_create($mode, &$entry) {
     global $serendipity;
@@ -625,13 +647,11 @@ function serendipity_iframe_create($mode, &$entry) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Pre-Checks certain server environments to indicate available options when installing Serendipity
  *
  * @access public
- * @param
- * @return
+ * @param   string      The name of the configuration option that needs to be checked for environmental data.
+ * @return  array       Returns the array of available options for the requested config option
  */
 function serendipity_probeInstallation($item) {
     global $serendipity;
@@ -668,13 +688,11 @@ function serendipity_probeInstallation($item) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Sets a HTTP header
  *
  * @access public
- * @param
- * @return
+ * @param   string      The HTTP headre to set
+ * @return null
  */
 function serendipity_header($header) {
     if (!headers_sent()) {
@@ -683,19 +701,18 @@ function serendipity_header($header) {
 }
 
 /**
- * SHORT
+ * Gets the currently selected language. Either from the browser, or the personal configuration, or the global configuration.
  *
- * LONG
+ * This function also sets HTTP Headers and cookies to contain the language for follow-up requests
+ * TODO:
+ * This previously was handled inside a plugin with an event hook, but caching
+ * the event plugins that early in sequence created trouble with plugins not
+ * having loaded the right language.
+ * Find a way to let plugins hook into that sequence :-)
  *
  * @access public
- * @param
- * @return
+ * @return  string      Returns the name of the selected language.
  */
-/* TODO:
-  This previously was handled inside a plugin with an event hook, but caching
-  the event plugins that early in sequence created trouble with plugins not
-  having loaded the right language.
-  Find a way to let plugins hook into that sequence :-) */
 function serendipity_getSessionLanguage() {
     global $serendipity;
 
@@ -736,13 +753,15 @@ function serendipity_getSessionLanguage() {
 }
 
 /**
- * SHORT
+ * Retrieves an array of applying permissions to an author
  *
- * LONG
+ * The privileges of each group an author is a member of are aggreated
+ * and stored in a larger array. So both memberships and all aplying
+ * privileges are returned.
  *
  * @access public
- * @param
- * @return
+ * @param   int     The ID of the author to fetch permissions/group memberships for
+ * @return  array   Multi-dimensional associative array which holds a 'membership' and permission name data
  */
 function &serendipity_getPermissions($authorid) {
     global $serendipity;
@@ -766,13 +785,14 @@ function &serendipity_getPermissions($authorid) {
 }
 
 /**
- * SHORT
+ * Returns the list of available internal Serendipity permission field names
  *
- * LONG
+ * This function also mapps which function was available to which userleves in older
+ * Serendipity versions. Thus if an author does not have a certain privilege he should
+ * have because of his userlevel, this can be reverse-mapped.
  *
  * @access public
- * @param
- * @return
+ * @return  array   Multi-dimensional associative array which the list of all permission items plus their userlevel associations
  */
 function serendipity_getPermissionNames() {
     return array(
@@ -850,13 +870,20 @@ function serendipity_getPermissionNames() {
 }
 
 /**
- * SHORT
+ * Checks if a permission is granted to a specific author
  *
- * LONG
+ * This function caches all permission chacks in static function variables to not
+ * fetch all permissions time and again.
+ * The permission checks are performed agains the values of each group. If a privilege
+ * is set in one of the groups the author is a user of, the function returns true.
+ * If a privilege is not set, the userlevel of an author is checked to act for backwards-compatibility.
  *
  * @access public
- * @param
- * @return
+ * @see serendipity_getPermissionNames()
+ * @param   string      The name of the permission to check
+ * @param   int         The authorid for which the permission check should be performed
+ * @param   boolean     If set to true, all groups that the requested author is a user of will be returned. This bypasses the permission check and mainly acts as a mean to return cached permissions, since those variables are only available within this function.
+ * @return  mixed       Either returns true if a permission check is performed, or return an array of group memberships. Depends on the $returnMyGroups variable.
  */
 function serendipity_checkPermission($permName, $authorid = null, $returnMyGroups = false) {
     global $serendipity;
@@ -918,12 +945,12 @@ function serendipity_checkPermission($permName, $authorid = null, $returnMyGroup
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Update author group membership(s)
  *
  * @access public
- * @param
+ * @param   array       The array of groups the author should be a member of. All memberships that were present before and not contained in this array will be removed.
+ * @param   int         The ID of the author to update
+ * @param   boolean     If set to true, the groups can only be updated if the user has the adminUsersMaintainOthers privilege. If set to false, group memberships will be changable for any user.
  * @return
  */
 function serendipity_updateGroups($groups, $authorid, $apply_acl = true) {
@@ -942,13 +969,15 @@ function serendipity_updateGroups($groups, $authorid, $apply_acl = true) {
 }
 
 /**
- * SHORT
+ * Returns all authorgroups that are available
  *
- * LONG
+ * If a groupname is prefixed with "USERLEVEL_" then the constant of that name is used to
+ * return the name of the group. This allows inserting the special groups Chief Editor, Editor
+ * and admin and still being able to use multilingual names for these groups.
  *
  * @access public
- * @param
- * @return
+ * @param   int     If set to an author ID value, only groups are fetched that this author is a member of. If set to false, all groups are returned, also those that the current user has no access to.
+ * @return  array   An associative array of group names.
  */
 function &serendipity_getAllGroups($apply_ACL_user = false) {
     global $serendipity;
@@ -982,13 +1011,11 @@ function &serendipity_getAllGroups($apply_ACL_user = false) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Fetch the permissions of a certain group
  *
  * @access public
- * @param
- * @return
+ * @param   int     The ID of the group that the permissions are fetched for
+ * @return  array   The associative array of permissions of a group.
  */
 function &serendipity_fetchGroup($groupid) {
     global $serendipity;
@@ -1019,12 +1046,11 @@ function &serendipity_fetchGroup($groupid) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Gets all groups a user is a member of
  *
  * @access public
- * @param
+ * @param   int         The authorid to fetch groups for
+ * @param   boolean     Indicate whether the original multi-dimensional DB result array shall be returned (FALSE) or if the array shall be flattened to be 1-dimensional (TRUE).
  * @return
  */
 function &serendipity_getGroups($authorid, $sequence = false) {
@@ -1054,13 +1080,11 @@ function &serendipity_getGroups($authorid, $sequence = false) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Gets all author IDs of a specific group
  *
  * @access public
- * @param
- * @return
+ * @param   int     The ID of the group to fetch the authors of
+ * @return  array   The assotiative array of author IDs and names
  */
 function &serendipity_getGroupUsers($groupid) {
     global $serendipity;
@@ -1078,13 +1102,11 @@ function &serendipity_getGroupUsers($groupid) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Deletes a specific author group by ID
  *
  * @access public
- * @param
- * @return
+ * @param   int     The group ID to delete
+ * @return  boolean Return true if group could be deleted, false if unsufficient privileges.
  */
 function serendipity_deleteGroup($groupid) {
     global $serendipity;
@@ -1108,13 +1130,11 @@ function serendipity_deleteGroup($groupid) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Creates a new author group
  *
  * @access public
- * @param
- * @return
+ * @param   string      The name of the new group
+ * @return  int         The id of the created group
  */
 function serendipity_addGroup($name) {
     global $serendipity;
@@ -1126,13 +1146,16 @@ function serendipity_addGroup($name) {
 }
 
 /**
- * SHORT
+ * Returns a list of all existing permission names.
  *
- * LONG
+ * Additional plugins might insert specific properties into the groupconfig database to 
+ * handle their own privileges. This call returns an array of all available permission names
+ * so that it can be intersected with the list of internal permission names (serendipity_getPermissionNames())
+ * and the be distincted.
  *
  * @access public
- * @param
- * @return
+ * @see serendipity_getPermissionNames()
+ * @return  array   associative array of all available permission names
  */
 function &serendipity_getDBPermissionNames() {
     global $serendipity;
@@ -1143,13 +1166,20 @@ function &serendipity_getDBPermissionNames() {
 }
 
 /**
- * SHORT
+ * Gets the list of all Permissions and merges the two arrays
  *
- * LONG
+ * The first call will fetch all existing permission names of the database. Then it will
+ * fetch the list of defined internal permission names, which has an array with extra information
+ * (like userlevel). This array will be merged with those permission names only found in the
+ * database. The returned array will then hold as much information about permission names as is
+ * available.
+ * TODO Might need further pushing and/or an event hook so that external plugins using the
+ * permission system can inject specific information into the array
  *
  * @access public
- * @param
- * @return
+ * @see serendipity_getPermissionNames()
+ * @see serendipity_getDBPermissionNames()
+ * @return  array   Returns the array with all information about all permission names
  */
 function &serendipity_getAllPermissionNames() {
     global $serendipity;
@@ -1167,13 +1197,20 @@ function &serendipity_getAllPermissionNames() {
 }
 
 /**
- * SHORT
+ * Checks if two users are members of the same group
  *
- * LONG
+ * This function will retrieve all group memeberships of a
+ * foreign user ($checkuser) and yourself ($myself). Then it
+ * will check if there is any group membership that those
+ * two users have in common.
+ * It can be used for detecting if a different author should
+ * be allowed to access your entries, because he's in the same
+ * group, for example.
  *
  * @access public
- * @param
- * @return
+ * @param   int     ID of the first author to check group memberships
+ * @param   int     ID of the second author to check group memberships
+ * @return  boolea  True if a membership intersects, false if not
  */
 function serendipity_intersectGroup($checkuser = null, $myself = null) {
     global $serendipity;
@@ -1195,13 +1232,14 @@ function serendipity_intersectGroup($checkuser = null, $myself = null) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Updates the configuration of permissions of a specific group
  *
+ * This function ensures that a group can only be updated from users that have permissions to do so.
  * @access public
- * @param
- * @return
+ * @param   int     The ID of the group to update
+ * @param   array   The associative array of permission names
+ * @param   array   The associative array of new values for the permissions. Needs the same associative keys like the $perms array.
+ * @return true
  */
 function serendipity_updateGroupConfig($groupid, &$perms, &$values) {
     global $serendipity;
@@ -1267,13 +1305,12 @@ function serendipity_updateGroupConfig($groupid, &$perms, &$values) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Adds a default internal group (Editor, Chief Editor, Admin)
  *
  * @access public
- * @param
- * @return
+ * @param   string  The name of the group to insert
+ * @param   int     The userlevel that represents this group (0|1|255 for Editor/Chief/Admin).
+ * @return true
  */
 function serendipity_addDefaultGroup($name, $level) {
     global $serendipity;
@@ -1307,13 +1344,20 @@ function serendipity_addDefaultGroup($name, $level) {
 }
 
 /**
- * SHORT
+ * Allow access to a specific item (category or entry) for a specific usergroup
  *
- * LONG
+ * ACL are Access Control Lists. They indicate which read/write permissions a
+ * specific item has for specific usergroups.
+ * An artifact in terms of Serendipity can be either a category or an entry, or
+ * anything beyond that for future compatibility.
+ * This function sets up the ACLs.
  *
  * @access public
- * @param
- * @return
+ * @param   int     The ID of the artifact to set the access
+ * @param   string  The type of an artifact (category|entry)
+ * @param   string  The type of access to grant (read|write)
+ * @param   array   The ID of the group to grant access to
+ * @return  boolean True if ACL was applied, false if not.
  */
 function serendipity_ACLGrant($artifact_id, $artifact_type, $artifact_mode, $groups) {
     global $serendipity;
@@ -1348,13 +1392,19 @@ function serendipity_ACLGrant($artifact_id, $artifact_type, $artifact_mode, $gro
 }
 
 /**
- * SHORT
- *
- * LONG
- *
+ * Checks if a specific item (category or entry) can be accessed by a specific usergroup
+ *
+ * ACL are Access Control Lists. They indicate which read/write permissions a
+ * specific item has for specific usergroups.
+ * An artifact in terms of Serendipity can be either a category or an entry, or
+ * anything beyond that for future compatibility.
+ * This function retrieves the ACLs.
+ * 
  * @access public
- * @param
- * @return
+ * @param   int     The ID of the artifact to set the access
+ * @param   string  The type of an artifact (category|entry)
+ * @param   string  The type of access to check for (read|write)
+ * @return  array   Returns an array of all groups that are allowed for this kind of access. You can then check if you are the member of any of the groups returned here.
  */
 function serendipity_ACLGet($artifact_id, $artifact_type, $artifact_mode) {
     global $serendipity;
@@ -1378,13 +1428,20 @@ function serendipity_ACLGet($artifact_id, $artifact_type, $artifact_mode) {
 }
 
 /**
- * SHORT
- *
- * LONG
- *
+ * Checks if a specific item (category or entry) can be accessed by a specific Author
+ *
+ * ACL are Access Control Lists. They indicate which read/write permissions a
+ * specific item has for specific usergroups.
+ * An artifact in terms of Serendipity can be either a category or an entry, or
+ * anything beyond that for future compatibility.
+ * This function retrieves the ACLs for a specific user.
+ * 
  * @access public
- * @param
- * @return
+ * @param   int     The ID of the author to check against.
+ * @param   int     The ID of the artifact to set the access
+ * @param   string  The type of an artifact ('category', more to come)
+ * @param   string  The type of access to check for (read|write)
+ * @return  boolean Returns true, if the author has access to this artifact. False if not.
  */
 function serendipity_ACLCheck($authorid, $artifact_id, $artifact_type, $artifact_mode) {
     global $serendipity;
@@ -1426,18 +1483,29 @@ function serendipity_ACLCheck($authorid, $artifact_id, $artifact_type, $artifact
 }
 
 /**
- * SHORT
- *
- * LONG
- *
- * @access public
- * @param
- * @return
+ * Prepares a SQL statement to be used in queries that should be ACL restricted.
+ *
+ * ACL are Access Control Lists. They indicate which read/write permissions a
+ * specific item has for specific usergroups.
+ * An artifact in terms of Serendipity can be either a category or an entry, or
+ * anything beyond that for future compatibility.
+ * This function evaluates and applies the SQL statements required.
+ * It is currently only written for retrieving Category ACLs.
+ * All of the SQL code that will be used in serendipity_fetchEntries will be stored
+ * within the referenced $cond array.
+ *
+ * @access private
+ * @param   array       Associative array that holds the SQL part array to be used in other functions like serendipity_fetchEntries()
+ * @param   boolean     Some queries do not need to joins categories. When ACLs need to be applied, this column is required, so if $append_category is set to true it will perform this missing JOIN.
+ * @return  true        True if ACLs were applied, false if not.
  */
 function serendipity_ACL_SQL(&$cond, $append_category = false) {
     global $serendipity;
 
+    // A global configuration item controls whether the blog should apply ACLs or not!
     if (!isset($serendipity['enableACL']) || $serendipity['enableACL'] == true) {
+
+        // If the user is logged in, we retrieve his authorid for the upcoming checks
         if ($_SESSION['serendipityAuthedUser'] === true) {
             $read_id = (int)$serendipity['authorid'];
             $read_id_sql = 'acl_a.groupid OR acl_acc.groupid = 0';
@@ -1490,13 +1558,13 @@ function serendipity_ACL_SQL(&$cond, $append_category = false) {
 }
 
 /**
- * SHORT
+ * Check for Cross-Site-Request-Forgery attacks because of missing HTTP Referer
  *
- * LONG
+ * http://de.wikipedia.org/wiki/XSRF
+ * This function checks the HTTP referer, and if it is part of the current Admin panel.
  *
  * @access public
- * @param
- * @return
+ * @return  Returns true if XSRF was detected, false if not. The script should abort, if TRUE is returned.
  */
 function serendipity_checkXSRF() {
     global $serendipity;
@@ -1540,13 +1608,18 @@ function serendipity_checkXSRF() {
 }
 
 /**
- * SHORT
+ * Report a XSRF attempt to the Serendipity Interface
+ *
+ * http://de.wikipedia.org/wiki/XSRF
  *
  * LONG
  *
  * @access public
- * @param
- * @return
+ * @see serendipity_checkXSRF()
+ * @param   string      The type of XSRF check that got hit. Used for CSS formatting.
+ * @param   boolean     If true, the XSRF error should be fatal
+ * @param   boolean     If true, tell Serendipity to check the $serendipity['referrerXSRF'] config option to decide if an error should be reported or not.
+ * @return  string      Returns the HTML error report
  */
 function serendipity_reportXSRF($type = 0, $reset = true, $use_config = false) {
     global $serendipity;
@@ -1568,13 +1641,15 @@ function serendipity_reportXSRF($type = 0, $reset = true, $use_config = false) {
 }
 
 /**
- * SHORT
+ * Prevent XSRF attacks by checking for a form token
  *
- * LONG
+ * http://de.wikipedia.org/wiki/XSRF
+ *
+ * This function checks, if a valid Form token was posted to the site.
  *
  * @access public
- * @param
- * @return
+ * @see serendipity_setFormToken()
+ * @return  boolean     Returns true, if XSRF attempt was found and the token was missing
  */
 function serendipity_checkFormToken() {
     global $serendipity;
@@ -1601,13 +1676,22 @@ function serendipity_checkFormToken() {
 }
 
 /**
- * SHORT
+/**
+ * Prevent XSRF attacks by setting a form token within HTTP Forms
  *
- * LONG
+ * http://de.wikipedia.org/wiki/XSRF
+ *
+ * By inserting a unique Form token that holds the session id, all requests
+ * to serendipity HTTP forms can only be processed if the token is present.
+ * This effectively makes XSRF attacks impossible. Only bundled with XSS
+ * attacks it can be bypassed.
+ *
+ * 'form' type tokens can be embedded within the <form> script.
+ * 'url' type token can be embedded within HTTP GET calls.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The type of token to return (form|url|plain)
+ * @return  string      Returns the form token to be used in your functions
  */
 function serendipity_setFormToken($type = 'form') {
     global $serendipity;
diff --git a/include/functions_entries.inc.php b/include/functions_entries.inc.php
index dd20ed6..3282d07 100644
--- a/include/functions_entries.inc.php
+++ b/include/functions_entries.inc.php
@@ -3,13 +3,12 @@
 # All rights reserved.  See LICENSE file for licensing details
 
 /**
- * SHORT
- *
- * LONG
+ * Delete a category or range of categories
  *
  * @access public
- * @param
- * @return
+ * @param   string  Holds the SQL string to pass to the 'BETWEEN' command. Like '1 5' would delete categories 1-5.
+ * @param   string  Holds the optional SQL string that contains an extra safety check so that only categories can be deleted if the user is an author of the category.
+ * @return  array   The DB result
  */
 function serendipity_deleteCategory($category_range, $admin_category) {
     global $serendipity;
@@ -24,13 +23,11 @@ function serendipity_deleteCategory($category_range, $admin_category) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Fetch a SQL ID subset of the category tree
  *
  * @access public
- * @param
- * @return
+ * @param   int     The Id of the parent category to fetch categorie childs from. (0: all)
+ * @return  array   An associative array of the left and right category next to the chosen one
  */
 function serendipity_fetchCategoryRange($categoryid) {
     global $serendipity;
@@ -44,13 +41,11 @@ function serendipity_fetchCategoryRange($categoryid) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Returns SQL code to use when fetching entries that are contained within multiple categories
  *
  * @access public
- * @param
- * @return
+ * @param  string   A listing of category ids to check, separated by ";"
+ * @return string   Returns the SQL code for selecting entries of the calculated categories
  */
 function serendipity_getMultiCategoriesSQL($cats) {
     global $serendipity;
@@ -69,13 +64,15 @@ function serendipity_getMultiCategoriesSQL($cats) {
 }
 
 /**
- * SHORT
+ * Return the category properties of a specific category
  *
- * LONG
+ * Either use the first or the second parameter to select a category by ID or name. It's not
+ * meant to be used with both parameters specified.
  *
  * @access public
- * @param
- * @return
+ * @param   int     The ID of the category to fetch
+ * @param   string  The Name of a category to fetch
+ * @return  array   Returns an array of category properties
  */
 function serendipity_fetchCategoryInfo($categoryid, $categoryname = '') {
     global $serendipity;
@@ -110,13 +107,11 @@ function serendipity_fetchCategoryInfo($categoryid, $categoryname = '') {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Fetch a list of all category properties to a specific entry ID
  *
  * @access public
- * @param
- * @return
+ * @param   int     The ID of the entry
+ * @return  array   The array of associated categories to that entry
  */
 function serendipity_fetchEntryCategories($entryid) {
   global $serendipity;
@@ -144,19 +139,46 @@ function serendipity_fetchEntryCategories($entryid) {
 
 
 /**
- * SHORT
+ * Fetch a list of entries
  *
- * LONG
+ * The most central and versatile function of Serendipity, allows you to fetch entries
+ * depending on a LOT of options.
+ * One of the parameters missing is a restriction by category. You need to do that by
+ * setting the superglobal $serendipity['GET']['category'] to the category you want to fetch.
+ * Separate multiple categories by ";".
+ * Other "external" variables that affect this function are:
+ *  $serendipity['short_archives']      - Indicates if the short archive listing is wanted, without the full entry text
+ *  $serendipity['range']               - If $range is not used, the time restriction is fetched from this array, which holds a start timestamp and end timestamp.
+ *  $serendipity['GET']['category']     - The category ID to restrict fetching entries from
+ *  $serendipity['GET']['viewAuthor']   - Only fetch entries by this author
+ *  $serendipity['GET']['page']         - The page number to show entries, for pagination
  *
- * @access public
- * @param
- * @return
+ * If you want to use any of these options, set the variable before calling serendipity_fetchEntries(). You can reset the variables to their original content after the function call, if you need to.
+ *
+ * Several options perform different commands when different types are passed, like the $range
+ * parameter which can either be a string or an array with START/END range.
+ *
+ * @access  public
+ * @param   mixed       Restricts fetching entries to a specific timespan. Behaves differently depending on the type:
+ *                      Numeric: 
+ *                        YYYYMMDD - Shows all entries from YYYY-MM-DD. 
+ *                                   If DD is "00", it will show all entries from that month. 
+ *                                   If DD is any other number, it will show entries of that specific day.
+ *                      2-Dimensional Array:
+ *                        Key #0   - Specifies the start timestamp (unix seconds)
+ *                        Key #1   - Specifies the end timestamp (unix seconds)
+ *                      Other (null, 3-dimensional Array, ...):
+ *                        Entries newer than $modified_since will be fetched 
+ * @param   boolean     Indicates if the full entry will be fetched (body+extended: TRUE), or only the body (FALSE).
+ * @param   string      Holds a "Y" or "X, Y" string that tells which entries to fetch. X is the first entry offset, Y is number of entries. If not set, the global fetchLimit will be applied (15 entries by default)
+ * @param   boolean     Indicates whether drafts should be fetched (TRUE) or not
+ * @param   int         Holds a unix timestamp to be used in conjunction with $range, to fetch all entries newer than this timestamp
+ * @param   string      Holds the SQL "ORDER BY" statement.
+ * @param   string      Can contain any SQL code to inject into the central SQL statement for fetching the entry
+ * @param   boolean     If set to TRUE, all entries will be fetched from scratch and any caching is ignored
+ * @param   boolean     If set to TRUE, all sticky entries will NOT be fetched.
+ * @return  array       Holds the super-array of all entries with all additional information
  */
-/**
-* Give it a range in YYYYMMDD format to gather the desired entries
-* (For february 2002 you would pass 200202 for all entries withing
-* two timestamps you would pass array(timestamp1,timestamp2)
-**/
 function serendipity_fetchEntries($range = null, $full = true, $limit = '', $fetchDrafts = false, $modified_since = false, $orderby = 'timestamp DESC', $filter_sql = '', $noCache = false, $noSticky = false) {
     global $serendipity;
 
@@ -347,16 +369,14 @@ function serendipity_fetchEntries($range = null, $full = true, $limit = '', $fet
 }
 
 /**
- * SHORT
+ * Fetch special entry data and attach it to a superarray of entries.
  *
- * LONG
+ * Fetches all additional information like plugins, extended properties, additional categories for each entry.
  *
- * @access public
- * @param
- * @return
- */
-/**
- * Attach special entry data to entry
+ * @access private
+ * @see serendipity_fetchEntries()
+ * @param   array       The array of entries where the output will be merged to (referenced)
+ * @return null
  */
 function serendipity_fetchEntryData(&$ret) {
     global $serendipity;
@@ -394,17 +414,15 @@ function serendipity_fetchEntryData(&$ret) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Fetch a single entry by a specific condition
  *
  * @access public
- * @param
+ * @param   string      The column to compare $val against (like 'id')
+ * @param   string      The value of the colum $key to compare with (like '4711')
+ * @param   boolean     Indicates if the full entry will be fetched (body+extended: TRUE), or only the body (FALSE).
+ * @param   string      Indicates whether drafts should be fetched
  * @return
  */
-/**
-* Fetches a specific entry
-**/
 function serendipity_fetchEntry($key, $val, $full = true, $fetchDrafts = 'false') {
     global $serendipity;
 
@@ -460,13 +478,11 @@ function serendipity_fetchEntry($key, $val, $full = true, $fetchDrafts = 'false'
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Fetches additional entry properties for a specific entry ID
  *
  * @access public
- * @param
- * @return
+ * @param   int     The ID of the entry to fetch additonal data for
+ * @return  array   The array of given properties to an entry
  */
 function serendipity_fetchEntryProperties($id) {
     global $serendipity;
@@ -488,17 +504,15 @@ function serendipity_fetchEntryProperties($id) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Fetch a list of available categories for an author
  *
  * @access public
- * @param
- * @return
+ * @param   mixed   If set, the list of categories will be fetched according to the author id. If not set, all categories will be fetched. If set to "all", then all categories will be fetched.
+ * @param   string  Restrict the list to be returned to a specific category NAME.
+ * @param   string  The SQL query part for ORDER BY of the categories
+ * @param   string  The ACL artifact condition. If set to "write" only categories will be shown that the author can write to. If set to "read", only categories will be show that the author can read or write to.
+ * @return  array   Returns the array of categories
  */
-/**
-* Fetches a users categories
-**/
 function serendipity_fetchCategories($authorid = null, $name = null, $order = null, $artifact_mode = 'write') {
     global $serendipity;
 
@@ -579,16 +593,15 @@ function serendipity_fetchCategories($authorid = null, $name = null, $order = nu
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Rebuild the Category Nested Set tree
  *
  * @access public
- * @param
- * @return
+ * @see Based on http://www.sitepoint.com/article/hierarchical-data-database/1
+ * @param   int     The ID of the parent category to rebuild
+ * @param   int     The ID of the next left category
+ * @return  int     Returns the new ID
  */
 function serendipity_rebuildCategoryTree($parent = 0, $left = 0) {
-    // Based on http://www.sitepoint.com/article/hierarchical-data-database/1
     global $serendipity;
     $right = $left + 1;
 
@@ -606,17 +619,14 @@ function serendipity_rebuildCategoryTree($parent = 0, $left = 0) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Searches the list of entries by a specific term
  *
+ * @todo: Allow to show results of staticpage plugins or others
  * @access public
- * @param
- * @return
+ * @param   string      The searchterm (may contain wildcards)
+ * @param   int         Restrict the number of results [also uses $serendipity['GET']['page'] for pagination]
+ * @return  array       Returns the superarray of entries found
  */
-/**
-* Give it a raw searchstring, it'll search
-**/
 function serendipity_searchEntries($term, $limit = '') {
     global $serendipity;
 
@@ -699,13 +709,13 @@ function serendipity_searchEntries($term, $limit = '') {
 }
 
 /**
- * SHORT
+ * Creates the Footer below the entries, with pagination options and parses it to Smarty
  *
- * LONG
+ * The list of total entries is calculated from the serendipity_getTotelEntries() function
  *
  * @access public
- * @param
- * @return
+ * @see serendipity_getTotalEntries()
+ * @return null
  */
 function serendipity_printEntryFooter() {
     global $serendipity;
@@ -742,6 +752,16 @@ function serendipity_printEntryFooter() {
     }
 }
 
+/**
+ * Calculates the amount of available entries.
+ *
+ * This function uses the SQL query portion of the central serendipity_fetchEntries() query
+ * and modifies it with different GROUP statements to calculate the number of entries.
+ *
+ * @access public
+ * @see serendipity_fetchEntries()
+ * @return int      The number of total entries
+ */
 function serendipity_getTotalEntries() {
     global $serendipity;
 
@@ -766,17 +786,27 @@ function serendipity_getTotalEntries() {
 }
 
 /**
- * SHORT
+ * Passes the list of fetched entries from serendipity_fetchEntries() on to the Smarty layer
  *
- * LONG
+ * This function contains all the core logic to group and prepare entries to be shown in your
+ * $entries.tpl template. It groups them by date, so that you can easily loop on the set of
+ * entries.
+ * This function is not only used for printing all entries, but also for printing individual
+ * entries.
+ * Several central Event hooks are executed here for the whole page flow, like header+footer data.
  *
+ * @see serendipity_fetchEntries()
+ * @see serendipity_searchEntries()
  * @access public
- * @param
+ * @param   array       The array of entries with all of its data
+ * @param   boolean     Toggle whether the extended portion of an entry is requested (via $serendipity['GET']['id'] single entry view)
+ * @param   boolean     Indicates if this is a preview
+ * @param   string      The name of the SMARTY block that this gets parsed into
+ * @param   boolean     Indicates whether the assigned smarty variables should be parsed
+ * @param   boolean     Indicates whether to apply footer/header event hooks
+ * @param   boolean     Indicates whether the pagination footer should be displayed
  * @return
  */
-/**
-* Prints the entries you fetched with serendipity_fetchEntries/searchEntries in HTML.
-**/
 function serendipity_printEntries($entries, $extended = 0, $preview = false, $smarty_block = 'ENTRIES', $smarty_fetch = true, $use_hooks = true, $use_footer = true) {
     global $serendipity;
 
@@ -942,17 +972,13 @@ function serendipity_printEntries($entries, $extended = 0, $preview = false, $sm
 } // end function serendipity_printEntries
 
 /**
- * SHORT
- *
- * LONG
+ * Deprecated: Delete some garbage when an entry was deleted, especially static pages
  *
+ * @deprecated
  * @access public
- * @param
- * @return
- */
-/**
-/**
- * purge a statically pregenerated entry
+ * @param   int     The deleted entry ID
+ * @param   int     A timestamp for the entry archive page
+ * @return null
  */
 function serendipity_purgeEntry($id, $timestamp = null) {
     global $serendipity;
@@ -979,17 +1005,14 @@ function serendipity_purgeEntry($id, $timestamp = null) {
 }
 
 /**
- * SHORT
+ * Inserts a new entry into the database or updates an existing entry
  *
- * LONG
+ * Another central function, that parses, prepares and commits changes to an entry
  *
  * @access public
- * @param
- * @return
+ * @param   array       The new/modified entry data.
+ * @return  mixed       Integer with new entry ID if successfull, a string or array if error(s).
  */
-/**
-* Inserts a new entry into the database or updates an existing
-**/
 function serendipity_updertEntry($entry) {
     global $serendipity;
 
@@ -1121,18 +1144,12 @@ function serendipity_updertEntry($entry) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Delete an entry and everything that belongs to it (comments)
  *
  * @access public
- * @param
- * @return
+ * @param   int     The Entry ID to delete
+ * @return  mixed   FALSE or NULL on error
  */
-/**
-* Deletes an entry and everything that belongs to it (comments, etc...) from
-* the database
-**/
 function serendipity_deleteEntry($id) {
     global $serendipity;
 
@@ -1160,23 +1177,16 @@ function serendipity_deleteEntry($id) {
 }
 
 /**
- * SHORT
- *
- * LONG
- *
- * @access public
- * @param
- * @return
- */
-/**
-* Print a list of categories
+* Return HTML containing a list of categories
 *
 * Prints a list of categories for use in forms, the sidebar, or whereever...
+*
+* @access public
 * @param array  An array of categories, typically gathered by serendipity_fetchCategories()
-* @param array  Select
-* @param int    Type
-* @param int    ID
-* @param int    Level
+* @param array  An array which holds IDs which are meant to be selected within a HTML SELECT form field [used for recursion]
+* @param int    The type of category list (0: HTML span list, 1/2: <option>s, 3: HTML Div list, 4: CSV data) to return
+* @param int    The parent ID of a category [for recursion]
+* @param int    The current nesting level [for recursion]
 * @param string Tells the function, whether or not to display the XML button for each category.
 *               If empty, no links to the xml feeds will be displayed; If you want to, you can
 *               pass an image here (this setting is only used, when type==3).
@@ -1236,13 +1246,12 @@ function serendipity_generateCategoryList($cats, $select = array(0), $type = 0,
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Set category associations of a specific entry
  *
  * @access public
- * @param
- * @return
+ * @param   int     The ID of the entry
+ * @param   array   An array of category IDs that this entry is associated to.
+ * @return null
  */
 function serendipity_updateEntryCategories($postid, $categories) {
     global $serendipity;
@@ -1265,13 +1274,13 @@ function serendipity_updateEntryCategories($postid, $categories) {
 }
 
 /**
- * SHORT
+ * Gather an archive listing of older entries and passes it to Smarty
  *
- * LONG
+ * The archives are created according to the current timestamp and show the current year.
+ * $serendipity['GET']['category'] is honoured like in serendipity_fetchEntries()
  *
  * @access public
- * @param
- * @return
+ * @return null
  */
 function serendipity_printArchives() {
     global $serendipity;
diff --git a/include/functions_entries_admin.inc.php b/include/functions_entries_admin.inc.php
index 954ab56..94bb2a2 100644
--- a/include/functions_entries_admin.inc.php
+++ b/include/functions_entries_admin.inc.php
@@ -5,17 +5,17 @@
 include_once(S9Y_INCLUDE_PATH . "include/functions_trackbacks.inc.php");
 
 /**
- * SHORT
+ * Prints the form for editing/creating new blog entries
  *
- * LONG
+ * This is the core file where your edit form appears. The Heart Of Gold, so to say.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The URL where the entry form is submitted to
+ * @param   array       An array of hidden input fields that should be passed on to the HTML FORM
+ * @param   array       The entry superarray with your entry's contents
+ * @param   string      Any error messages that might have occured on the last run
+ * @return null
  */
-/**
-* Prints a form to enter new diary entries
-**/
 function serendipity_printEntryForm($targetURL, $hiddens = array(), $entry = array(), $errMsg = "") {
     global $serendipity;
 
diff --git a/include/functions_images.inc.php b/include/functions_images.inc.php
index cc9399e..8d1f143 100644
--- a/include/functions_images.inc.php
+++ b/include/functions_images.inc.php
@@ -3,13 +3,11 @@
 # All rights reserved.  See LICENSE file for licensing details
 
 /**
- * SHORT
- *
- * LONG
+ * Check if an uploaded file is "evil"
  *
  * @access public
- * @param
- * @return
+ * @param   string  Input filename
+ * @return boolean
  */
 function serendipity_isActiveFile($file) {
     if (preg_match('@^\.@', $file)) {
@@ -20,17 +18,20 @@ function serendipity_isActiveFile($file) {
 }
 
 /**
- * SHORT
+ * Gets a list of media items from our media database
  *
  * LONG
  *
  * @access public
- * @param
- * @return
+ * @param   int     The offset to start fetching media files
+ * @param   int     How many items to fetch
+ * @param   int     The number (referenced varaible) of fetched items
+ * @param   string  The "ORDER BY" sql part when fetching items
+ * @param   string  Order by DESC or ASC
+ * @param   string  Only fetch files from a specific directory
+ * @param   string  Only fetch specific filenames
+ * @return  array   Resultset of images
  */
-/**
-* Get a list of images
-**/
 function serendipity_fetchImagesFromDatabase($start=0, $limit=0, &$total, $order = false, $ordermode = false, $directory = '', $filename = '') {
     global $serendipity;
 
@@ -86,13 +87,11 @@ function serendipity_fetchImagesFromDatabase($start=0, $limit=0, &$total, $order
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Fetch a specific media item from the mediadatabase
  *
  * @access public
- * @param
- * @return
+ * @param   int     The ID of an media item
+ * @return  array   The media info data
  */
 function serendipity_fetchImageFromDatabase($id) {
     global $serendipity;
@@ -101,13 +100,12 @@ function serendipity_fetchImageFromDatabase($id) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Update a media item
  *
  * @access public
- * @param
- * @return
+ * @param   array       An array of columns to update
+ * @param   int         The ID of an media item to update
+ * @return  boolean
  */
 function serendipity_updateImageInDatabase($updates, $id) {
     global $serendipity;
@@ -129,12 +127,10 @@ function serendipity_updateImageInDatabase($updates, $id) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Delete a media item
  *
  * @access public
- * @param
+ * @param   int     The ID of a media item to delete
  * @return
  */
 function serendipity_deleteImage($id) {
@@ -175,17 +171,16 @@ function serendipity_deleteImage($id) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Open a directory and fetch all existing media items
  *
  * @access public
- * @param
- * @return
+ * @param   boolean     deprecated
+ * @param   int         deprecated
+ * @param   int         deprecated
+ * @param   array       Array list of found items
+ * @param   string      sub-directory to investigate [recursive use]
+ * @return  array       List of media items
  */
-/**
-* Get a list of images
-**/
 function serendipity_fetchImages($group = false, $start = 0, $end = 20, $images = '', $odir = '') {
     global $serendipity;
 
@@ -215,13 +210,17 @@ function serendipity_fetchImages($group = false, $start = 0, $end = 20, $images
 }
 
 /**
- * SHORT
+ * Inserts a hotlinked media file
  *
- * LONG
+ * hotlinks are files that are only linked in your database, and not really stored on your server
  *
  * @access public
- * @param
- * @return
+ * @param   string      The filename to hotlink
+ * @param   string      The URL to hotlink with
+ * @param   int         The owner of the hotlinked media item
+ * @param   int         The timestamp of insertion (unix second)
+ * @param   string      A temporary filename for fetching the file to investigate it
+ * @return  int         The ID of the inserted media item
  */
 function serendipity_insertHotlinkedImageInDatabase($filename, $url, $authorid = 0, $time = NULL, $tempfile = NULL) {
     global $serendipity;
@@ -291,13 +290,14 @@ function serendipity_insertHotlinkedImageInDatabase($filename, $url, $authorid =
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Insert a media item in the database
  *
  * @access public
- * @param
- * @return
+ * @param   string      The filename of the media item
+ * @param   string      The path to the media item
+ * @param   int         The owner author of the item
+ * @param   int         The timestamp of when the media item was inserted
+ * @return  int         The new media ID
  */
 function serendipity_insertImageInDatabase($filename, $directory, $authorid = 0, $time = NULL) {
     global $serendipity;
@@ -372,17 +372,16 @@ function serendipity_insertImageInDatabase($filename, $directory, $authorid = 0,
 
 
 /**
- * SHORT
+ * Create a thumbnail for an image
  *
  * LONG
  *
  * @access public
- * @param
- * @return
+ * @param   string      The input image filename
+ * @param   string      The directory to the image file
+ * @param   array       The target size of the thumbnail (2-dimensional array width,height)
+ * @return  array       The result size of the thumbnail
  */
-/**
-* Generate a thumbnail
-**/
 function serendipity_makeThumbnail($file, $directory = '', $size = false) {
     global $serendipity;
 
@@ -428,17 +427,16 @@ function serendipity_makeThumbnail($file, $directory = '', $size = false) {
 }
 
 /**
- * SHORT
+ * Scale an image
  *
  * LONG
  *
  * @access public
- * @param
- * @return
+ * @param   int     The ID of an image
+ * @param   int     The target width
+ * @param   int     The target height
+ * @return true
  */
-/**
-*  Scale an image (ignoring proportions)
-**/
 function serendipity_scaleImg($id, $width, $height) {
     global $serendipity;
 
@@ -467,17 +465,15 @@ function serendipity_scaleImg($id, $width, $height) {
 }
 
 /**
- * SHORT
+ * Rotate an image
  *
  * LONG
  *
  * @access public
- * @param
- * @return
+ * @param   int     The ID of an image
+ * @param   int     Number of degrees to rotate
+ * @return boolean
  */
-/**
- * Rotate an Image
- **/
 function serendipity_rotateImg($id, $degrees) {
     global $serendipity;
 
@@ -526,17 +522,11 @@ function serendipity_rotateImg($id, $degrees) {
 
 
 /**
- * SHORT
- *
- * LONG
+ * Creates thumbnails for all images in the upload dir
  *
  * @access public
- * @param
- * @return
+ * @return  int Number of created thumbnails
  */
-/**
-* Creates thumbnails for all images in the upload dir
-**/
 function serendipity_generateThumbs() {
     global $serendipity;
 
@@ -598,13 +588,11 @@ function serendipity_generateThumbs() {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Guess the MIME type of a file
  *
  * @access public
- * @param
- * @return
+ * @param   string  Filename extension
+ * @return  string  Mimetype
  */
 function serendipity_guessMime($extension) {
     $mime = '';
@@ -802,17 +790,13 @@ function serendipity_guessMime($extension) {
 }
 
 /**
- * SHORT
+ * Check all existing thumbnails if they are the right size, insert missing thumbnails
  *
  * LONG
  *
  * @access public
- * @param
- * @return
+ * @return  int     Number of updated thumbnails
  */
-/**
-* Creates thumbnails for all images in the upload dir
-**/
 function serendipity_syncThumbs() {
     global $serendipity;
 
@@ -884,13 +868,11 @@ function serendipity_syncThumbs() {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Wrapper for GDLib functions
  *
  * @access public
- * @param
- * @return
+ * @param   string      Filename to operate on
+ * @return string       Functionname to execute
  */
 function serendipity_functions_gd($infilename) {
     if (!function_exists('imagecopyresampled')) {
@@ -939,13 +921,13 @@ function serendipity_functions_gd($infilename) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Rotate an image (GDlib)
  *
  * @access public
- * @param
- * @return
+ * @param   string      Source Filename to rotate
+ * @param   string      Target file
+ * @param   int         Degress to rotate
+ * @return  array       New width/height of the image
  */
 function serendipity_rotate_image_gd($infilename, $outfilename, $degrees)
 {
@@ -970,13 +952,14 @@ function serendipity_rotate_image_gd($infilename, $outfilename, $degrees)
 
 
 /**
- * SHORT
- *
- * LONG
+ * Resize an image (GDLib)
  *
  * @access public
- * @param
- * @return
+ * @param   string      Source Filename to resize
+ * @param   string      Target file
+ * @param   int         New width
+ * @return  int         New height (can be autodetected)
+ * @return  array       New image size
  */
 function serendipity_resize_image_gd($infilename, $outfilename, $newwidth, $newheight=null)
 {
@@ -1012,13 +995,13 @@ function serendipity_resize_image_gd($infilename, $outfilename, $newwidth, $newh
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Calculate aspect ratio of an image
  *
  * @access public
- * @param
- * @return
+ * @param   int     Image width
+ * @param   int     Image height
+ * @param   int     Target width
+ * @return  int     Target height
  */
 function serendipity_calculate_aspect_size($width, $height, $newwidth) {
 
@@ -1047,13 +1030,16 @@ function serendipity_calculate_aspect_size($width, $height, $newwidth) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Display the list of images in our database
  *
  * @access public
- * @param
- * @return
+ * @param   int     The current page number
+ * @param   string  The HTML linebreak to use after a row of images
+ * @param   boolean Should the toolbar for editing media files be shown?
+ * @param   string  The URL to use for pagination
+ * @param   boolean Show the "upload media item" feature?
+ * @param   boolean Restrict viewing images to a specific directory
+ * @return null
  */
 function serendipity_displayImageList($page = 0, $lineBreak = NULL, $manage = false, $url = NULL, $show_upload = false, $limit_path = NULL) {
     global $serendipity;
@@ -1295,13 +1281,12 @@ if ( !$manage ) {
 } // End serendipity_displayImageList()
 
 /**
- * SHORT
- *
- * LONG
+ * Check if a media item is an image
  *
  * @access public
- * @param
- * @return
+ * @param   array       File information
+ * @param   boolean     Use a strict check that does not list PDFs as an image?
+ * @return  boolean     True if the file is an image
  */
 function serendipity_isImage(&$file, $strict = false) {
     global $serendipity;
@@ -1321,13 +1306,13 @@ function serendipity_isImage(&$file, $strict = false) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Recursively delete a directory tree
  *
  * @access public
- * @param
- * @return
+ * @param   string      The originating directory
+ * @param   string      The subdirectory
+ * @param   boolean     Force deleting an directory even if there are files left in it?
+ * @return true
  */
 function serendipity_killPath($basedir, $directory = '', $forceDelete = false) {
     static $n = "<br />\n";
@@ -1402,13 +1387,16 @@ function serendipity_killPath($basedir, $directory = '', $forceDelete = false) {
 
 
 /**
- * SHORT
- *
- * LONG
+ * Recursively walk a directory tree
  *
  * @access public
- * @param
- * @return
+ * @param   string      The core directory
+ * @param   string      The subdirectory
+ * @param   boolean     Only return directories instead of files as well?
+ * @param   string      A regexp patter to include files
+ * @param   int         Level of nesting (recursive use)
+ * @param   int         The maximum level of nesting (recursive use)
+ * @return  array       Array of files/directories
  */
 function serendipity_traversePath($basedir, $dir='', $onlyDirs=true, $pattern = NULL, $depth = 1, $max_depth = null) {
 
@@ -1441,12 +1429,10 @@ function serendipity_traversePath($basedir, $dir='', $onlyDirs=true, $pattern =
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Delete a directory with all its files
  *
  * @access public
- * @param
+ * @param   string      The directory to delete
  * @return
  */
 function serendipity_deletePath($dir) {
@@ -1470,13 +1456,13 @@ function serendipity_deletePath($dir) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Check if a entered HTTP upload path is valid
  *
  * @access public
- * @param
- * @return
+ * @param   string      The input filename
+ * @param   boolean     Shall all paths be stripped?
+ * @param   boolean     Shall a trailing slash be appended?
+ * @return  string      The condom-wrapped path/file info
  */
 function serendipity_uploadSecure($var, $strip_paths = true, $append_slash = false) {
     $var = preg_replace('@[^0-9a-z\._/-]@i', '', $var);
@@ -1496,13 +1482,13 @@ function serendipity_uploadSecure($var, $strip_paths = true, $append_slash = fal
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Get the imagesize for a file
  *
  * @access public
- * @param
- * @return
+ * @param   string      The filename of the image
+ * @param   string      The mimetype of an image (can be autodetected)
+ * @param   string      The file extension of an image
+ * @return  array       The width/height of the file
  */
 function serendipity_getimagesize($file, $ft_mime = '', $suf = '') {
     if (empty($ft_mime) && !empty($suf)) {
@@ -1538,13 +1524,10 @@ function serendipity_getimagesize($file, $ft_mime = '', $suf = '') {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Get the available fields of the media database
  *
  * @access public
- * @param
- * @return
+ * @return array    Array with available, sortable fields
  */
 function serendipity_getImageFields() {
     return array(
@@ -1559,13 +1542,11 @@ function serendipity_getImageFields() {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Escape a shell argument for imagemagick use
  *
  * @access public
- * @param
- * @return
+ * @param   string  Input argument
+ * @return  string  Output argument
  */
 function serendipity_escapeshellarg($string) {
     return escapeshellarg(str_replace('%', '', $string));
diff --git a/include/functions_installer.inc.php b/include/functions_installer.inc.php
index 6554674..77eca91 100644
--- a/include/functions_installer.inc.php
+++ b/include/functions_installer.inc.php
@@ -4,26 +4,22 @@
 
 
 /**
- * SHORT
- *
- * LONG
+ * Convert a PHP Ini setting to a boolean flag
  *
  * @access public
- * @param
- * @return
+ * @param   mixed       input variable
+ * @return  boolean     output variable
  */
 function serendipity_ini_bool($var) {
     return ($var === 'on' || $var == '1');
 }
 
 /**
- * SHORT
- *
- * LONG
+ * convert a size value from a PHP.ini to a bytesize
  *
  * @access public
- * @param
- * @return
+ * @param   string  size value from PHP.ini
+ * @return  string  bytesize
  */
 function serendipity_ini_bytesize($val) {
     if ( $val == '' )
@@ -44,13 +40,18 @@ function serendipity_ini_bytesize($val) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Update the serendipity_config_local.inc.php file with core information
  *
  * @access public
- * @param
- * @return
+ * @param   string  Database name
+ * @param   string  Database prefix
+ * @param   string  Database host
+ * @param   string  Database user
+ * @param   string  Datapase Passwort
+ * @param   string  Database type
+ * @param   string  Use persistent connections?
+ * @param   array   An array of additional variables to be put into the config file
+ * @return true
  */
 function serendipity_updateLocalConfig($dbName, $dbPrefix, $dbHost, $dbUser, $dbPass, $dbType, $dbPersistent, $privateVariables = null) {
     global $serendipity;
@@ -117,18 +118,14 @@ function serendipity_updateLocalConfig($dbName, $dbPrefix, $dbHost, $dbUser, $db
 }
 
 /**
- * SHORT
+ * Setup the core database tables
  *
- * LONG
+ * Creates the needed tables - beware, they will be empty and need to be stuffed with
+ * default templates and such...
  *
  * @access public
- * @param
- * @return
+ * @return null
  */
-/**
-* Creates the needed tables - beware, they will be empty and need to be stuffed with
-* default templates and such...
-*/
 function serendipity_installDatabase() {
   global $serendipity;
   $queries = serendipity_parse_sql_tables(S9Y_INCLUDE_PATH . 'sql/db.sql');
@@ -140,13 +137,14 @@ function serendipity_installDatabase() {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Check a default value of a config item from the configuration template files
  *
  * @access public
- * @param
- * @return
+ * @param   string      Name of the config item to check
+ * @param   string      The default value, if none is found
+ * @param   boolean     If true, it's the personal config template, if false its the global config template
+ * @param   string      Protected fields will not be echo'd in the HTML form
+ * @return  string      The default value
  */
 function serendipity_query_default($optname, $default, $usertemplate = false, $type = 'string') {
     global $serendipity;
@@ -235,13 +233,13 @@ function serendipity_query_default($optname, $default, $usertemplate = false, $t
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Parse a configuration template file
  *
  * @access public
- * @param
- * @return
+ * @param   string      Path to the s9y configuration template file
+ * @param   array       An array of config areas/sections that shall be returned from the template
+ * @param   array       Restrict the return of template variables to items containing a specific flag
+ * @return  array        An array with configuration items, keys and values
  */
 function serendipity_parseTemplate($filename, $areas = null, $onlyFlags=null) {
     global $serendipity;
@@ -321,13 +319,11 @@ function serendipity_parseTemplate($filename, $areas = null, $onlyFlags=null) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Replace some variables within config item values with the right values
  *
  * @access public
- * @param
- * @return
+ * @param   string  Input string
+ * @return  string  Output string
  */
 function serendipity_replaceEmbeddedConfigVars ($s) {
     return str_replace(
@@ -343,13 +339,14 @@ function serendipity_replaceEmbeddedConfigVars ($s) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Preprocess the configuration value and put it into a HTML output field (radio, password, text, select, ...)
  *
  * @access public
- * @param
- * @return
+ * @param   string  The type of the configuration item
+ * @param   string  The name of the configuration item
+ * @param   string  The current value of the configuration item
+ * @param   string  The default value of the configuration item
+ * @return null
  */
 function serendipity_guessInput($type, $name, $value='', $default='') {
     global $serendipity;
@@ -411,13 +408,15 @@ function serendipity_guessInput($type, $name, $value='', $default='') {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Parses the configuration array and displays the configuration screen
  *
  * @access public
- * @param
- * @return
+ * @param   array       Configuration superarray
+ * @param   array       The previous values submitted by the user
+ * @param   boolean     If true, no HTML FORM container will be emitted
+ * @param   boolean     If true, the configuration sections will all be folded
+ * @param   boolean     If true, the user can turn config sections on and off
+ * @return null
  */
 function serendipity_printConfigTemplate($config, $from = false, $noForm = false, $folded = true, $allowToggle = true) {
     global $serendipity;
@@ -577,13 +576,11 @@ function showConfigAll(count) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Parse .sql files for use within Serendipity, query by query
  *
  * @access public
- * @param
- * @return
+ * @param   string  The filename of the SQL file
+ * @return array    An array of queries to execute
  */
 function serendipity_parse_sql_tables($filename) {
     $in_table = 0;
@@ -617,13 +614,10 @@ function serendipity_parse_sql_tables($filename) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Check the serendipity Installation for problems, during installation
  *
  * @access public
- * @param
- * @return
+ * @return boolean  Errors encountered?
  */
 function serendipity_checkInstallation() {
     global $serendipity, $umask;
@@ -693,13 +687,11 @@ function serendipity_checkInstallation() {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Create the files needed by Serendipity [htaccess/serendipity_config_local.inc.php]
  *
  * @access public
- * @param
- * @return
+ * @param   string      Path to the serendipity directory
+ * @return  true
  */
 function serendipity_installFiles($serendipity_core = '') {
     global $serendipity;
@@ -855,15 +847,13 @@ function serendipity_installFiles($serendipity_core = '') {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Check the flags of a configuration item for their belonging into a template
  *
  * @access public
- * @param
- * @return
+ * @param   array       An item to check
+ * @param   array       The area (configuration|local) where the config item might be displayed
+ * @return  boolean
  */
-/* Takes the item data from a config var, and checks the flags against the current area */
 function serendipity_checkConfigItemFlags(&$item, $area) {
 
     if ( in_array('nosave', $item['flags']) ) {
@@ -882,13 +872,10 @@ function serendipity_checkConfigItemFlags(&$item, $area) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * When paths or other options are changed in the s9y configuration, update the core files
  *
  * @access public
- * @param
- * @return
+ * @return boolean
  */
 function serendipity_updateConfiguration() {
     global $serendipity, $umask;
@@ -958,13 +945,10 @@ function serendipity_updateConfiguration() {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Get the root directory of Serendipity
  *
  * @access public
- * @param
- * @return
+ * @return  string      The root directory of Serendipity
  */
 function serendipity_httpCoreDir() {
     if (!empty($_SERVER['SCRIPT_FILENAME']) && substr(php_sapi_name(), 0, 3) != 'cgi') {
@@ -975,13 +959,11 @@ function serendipity_httpCoreDir() {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Delete obsolete files from Serendipity
  *
  * @access public
- * @param
- * @return
+ * @param   array       List of files to remove (backup is tried)
+ * @return boolean
  */
 function serendipity_removeFiles($files = null) {
     global $serendipity, $errors;
@@ -1026,13 +1008,11 @@ function serendipity_removeFiles($files = null) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Get the real directory of this function file
  *
  * @access public
- * @param
- * @return
+ * @param   string      A filename to strip extra paths from
+ * @return  string      The real directory name
  */
 function serendipity_getRealDir($file) {
     $dir = str_replace( "\\", "/", dirname($file));
@@ -1041,13 +1021,13 @@ function serendipity_getRealDir($file) {
 }
 
 /**
- * SHORT
+ * Try to detect if apache URL rewriting is available
  *
- * LONG
+ * This function makes a dummy HTTP request and sees if it works
  *
  * @access public
- * @param
- * @return
+ * @param   string      The default option when rewrite fails
+ * @return  string      The best preference option for URL rewriting
  */
 function serendipity_check_rewrite($default) {
     global $serendipity;
@@ -1106,13 +1086,10 @@ function serendipity_check_rewrite($default) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Remove old configuration values that are no longer used by Serendipity
  *
  * @access public
- * @param
- * @return
+ * @return null
  */
 function serendipity_removeObsoleteVars() {
 global $serendipity;
diff --git a/include/functions_permalinks.inc.php b/include/functions_permalinks.inc.php
index 32d16dd..54dc42c 100644
--- a/include/functions_permalinks.inc.php
+++ b/include/functions_permalinks.inc.php
@@ -3,13 +3,12 @@
 # All rights reserved.  See LICENSE file for licensing details
 
 /**
- * SHORT
- *
- * LONG
+ * Converts a string into a filename that can be used safely in HTTP URLs
  *
  * @access public
- * @param
- * @return
+ * @param   string  input string
+ * @param   boolean Shall dots in the filename be removed? (Required for certain regex rules)
+ * @return  string  output string
  */
 function serendipity_makeFilename($str, $stripDots = false) {
     static $from = array(
@@ -139,13 +138,10 @@ function serendipity_makeFilename($str, $stripDots = false) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Initialize permalinks, if the user did not specify those yet
  *
  * @access public
- * @param
- * @return
+ * @return null
  */
 function serendipity_initPermalinks() {
     global $serendipity;
@@ -244,13 +240,11 @@ function serendipity_initPermalinks() {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Build an array containing all regular expression permalinks
  *
  * @access public
- * @param
- * @return
+ * @param   boolean     If set to true, the list of permalinks will be returned. If false, all permalinks will be applied as Constants
+ * @return  array       (conditional on $return) List of permalinks
  */
 function &serendipity_permalinkPatterns($return = false) {
     global $serendipity;
@@ -286,13 +280,17 @@ function &serendipity_permalinkPatterns($return = false) {
 }
 
 /**
- * SHORT
+ * Search the reference to a specific permalink
  *
- * LONG
+ * This query will show the Entry/Category/Author-ID to a permalink, if that permalink
+ * does not contain %id%.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The permalink configuration string
+ * @param   string      The URL to check
+ * @param   string      A default return value if no permalink is found
+ * @param   string      The type of a permalink (entry|category|author)
+ * @return  string      The ID of the permalink type
  */
 function serendipity_searchPermalink($struct, $url, $default, $type = 'entry') {
     global $serendipity;
@@ -320,13 +318,15 @@ function serendipity_searchPermalink($struct, $url, $default, $type = 'entry') {
 }
 
 /**
- * SHORT
+ * Create a permalink for the given input data
  *
- * LONG
+ * You can pass an entry array, or an author array to this function
+ * and then get a permalink valid for that array
  *
  * @access public
- * @param
- * @return
+ * @param   array       The input data used for building the permalink
+ * @param   string      The type of the permalink (entry|category|author)
+ * @return  string      The permalink
  */
 function serendipity_getPermalink(&$data, $type = 'entry') {
     switch($type) {
@@ -353,13 +353,12 @@ function serendipity_getPermalink(&$data, $type = 'entry') {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Update a permalink with new data
  *
  * @access public
- * @param
- * @return
+ * @param   array       The input data used for building the permalink
+ * @param   string      The type of the permalink (entry|category|author)
+ * @return  string      The database result
  */
 function serendipity_updatePermalink(&$data, $type = 'entry') {
     global $serendipity;
@@ -376,13 +375,14 @@ function serendipity_updatePermalink(&$data, $type = 'entry') {
 }
 
 /**
- * SHORT
+ * Insert a new Permalink into the database for latter retrieval
  *
- * LONG
+ * This function is basically only used if you have no '%id%' value in your permalink config.
  *
  * @access public
- * @param
- * @return
+ * @param   array       The input data used for building the permalink
+ * @param   string      The type of the permalink (entry|category|author)
+ * @return  string      The permalink
  */
 function serendipity_insertPermalink(&$data, $type = 'entry') {
     global $serendipity;
@@ -413,13 +413,10 @@ function serendipity_insertPermalink(&$data, $type = 'entry') {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Build all permalinks for all current entries, authors and categories
  *
  * @access public
- * @param
- * @return
+ * @return null
  */
 function serendipity_buildPermalinks() {
     global $serendipity;
@@ -456,28 +453,27 @@ function serendipity_buildPermalinks() {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Uses logic to figure out how the URI should look, based on current rewrite rule
  *
  * @access public
- * @param
- * @return
+ * @param   string      The URL part that you want to format to "pretty urls"
+ * @param   string      The path/URL you want as a prefix for your pretty URL
+ * @param   boolean     If set to TRUE this will bypass all pretty URLs and format the link so that it works everywhere
+ * @return  string      The rewritten URL
  */
-/* Uses logic to figure out how the URI should look, based on current rewrite rule */
 function serendipity_rewriteURL($path, $key='baseURL', $forceNone = false) {
     global $serendipity;
     return $serendipity[$key] . ($serendipity['rewrite'] == 'none' || ($serendipity['rewrite'] != 'none' && $forceNone) ? $serendipity['indexFile'] . '?/' : '') . $path;
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Format a permalink according to the configured format
  *
  * @access public
- * @param
- * @return
+ * @param   string      The URL format to use
+ * @param   array       The input data to format a permalink
+ * @param   string      The type of the permalink (entry|category|author)
+ * @return  string      The formatted permalink
  */
 function serendipity_makePermalink($format, $data, $type = 'entry') {
     global $serendipity;
@@ -536,13 +532,12 @@ function serendipity_makePermalink($format, $data, $type = 'entry') {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Convert a permalink configuration into a regular expression for use in rewrite rules
  *
  * @access public
- * @param
- * @return
+ * @param   string      The URL format to use
+ * @param   string      The type of the permalink (entry|category|author)
+ * @return  string      The regular expression to a permalink URL
  */
 function serendipity_makePermalinkRegex($format, $type = 'entry') {
     static $entryKeys           = array('%id%',     '%title%',              '%day%',      '%month%',    '%year%');
@@ -570,13 +565,15 @@ function serendipity_makePermalinkRegex($format, $type = 'entry') {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Create a permalink for an entry permalink
  *
  * @access public
- * @param
- * @return
+ * @param   int     The entry ID
+ * @param   string  The entry title
+ * @param   string  The base URL/path key
+ * @param   boolean Shall the link be rewritten to a pretty URL?
+ * @param   array   Additional entry data
+ * @return  string  The permalink
  */
 function serendipity_archiveURL($id, $title, $key = 'baseURL', $checkrewrite = true, $entryData = null) {
     global $serendipity;
@@ -588,13 +585,13 @@ function serendipity_archiveURL($id, $title, $key = 'baseURL', $checkrewrite = t
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Create a permalink for an authors permalink
  *
  * @access public
- * @param
- * @return
+ * @param   array   The author data
+ * @param   string  The base URL/path key
+ * @param   boolean Shall the link be rewritten to a pretty URL?
+ * @return  string  The permalink
  */
 function serendipity_authorURL(&$data, $key = 'baseURL', $checkrewrite = true) {
     global $serendipity;
@@ -606,13 +603,13 @@ function serendipity_authorURL(&$data, $key = 'baseURL', $checkrewrite = true) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Create a permalink for an category permalink
  *
  * @access public
- * @param
- * @return
+ * @param   array   The category data
+ * @param   string  The base URL/path key
+ * @param   boolean Shall the link be rewritten to a pretty URL?
+ * @return  string  The permalink
  */
 function serendipity_categoryURL(&$data, $key = 'baseURL', $checkrewrite = true) {
     global $serendipity;
@@ -624,13 +621,13 @@ function serendipity_categoryURL(&$data, $key = 'baseURL', $checkrewrite = true)
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Create a permalink for an RSS feed permalink
  *
  * @access public
- * @param
- * @return
+ * @param   array   The entry data
+ * @param   string  The base URL/path key
+ * @param   boolean Shall the link be rewritten to a pretty URL?
+ * @return  string  The permalink
  */
 function serendipity_feedCategoryURL(&$data, $key = 'baseURL', $checkrewrite = true) {
     global $serendipity;
@@ -642,13 +639,13 @@ function serendipity_feedCategoryURL(&$data, $key = 'baseURL', $checkrewrite = t
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Create a permalink for an RSS authors' feed permalink
  *
  * @access public
- * @param
- * @return
+ * @param   array   The entry data
+ * @param   string  The base URL/path key
+ * @param   boolean Shall the link be rewritten to a pretty URL?
+ * @return  string  The permalink
  */
 function serendipity_feedAuthorURL(&$data, $key = 'baseURL', $checkrewrite = true) {
     global $serendipity;
@@ -660,26 +657,23 @@ function serendipity_feedAuthorURL(&$data, $key = 'baseURL', $checkrewrite = tru
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Create a permalink for an archive date
  *
  * @access public
- * @param
- * @return
+ * @param   string  The archive's date
+ * @param   boolean If true, only summary archive
+ * @param   string  The base URL/path key
+ * @return  string  The permalink
  */
 function serendipity_archiveDateUrl($range, $summary=false, $key='baseURL') {
     return serendipity_rewriteURL(PATH_ARCHIVES . '/' . $range . ($summary ? '/summary' : '') . '.html', $key);
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Returns the URL to the current page that is being viewed
  *
  * @access public
- * @param
- * @return
+ * @return string   the current URL
  */
 function serendipity_currentURL() {
     global $serendipity;
@@ -717,12 +711,11 @@ function serendipity_currentURL() {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Get the URI Arguments for the current HTTP Request
  *
  * @access public
- * @param
+ * @param   string      The URI made for this request
+ * @param   boolean     If enabled, then no Dots are allowed in the URL for permalinks
  * @return
  */
 function serendipity_getUriArguments($uri, $wildcard = false) {
diff --git a/include/functions_rss.inc.php b/include/functions_rss.inc.php
index f73d5e7..341feda 100644
--- a/include/functions_rss.inc.php
+++ b/include/functions_rss.inc.php
@@ -3,12 +3,18 @@
 # All rights reserved.  See LICENSE file for licensing details
 
 /**
- * SHORT
+ * Parses entries to display them for RSS/Atom feeds to be passed on to generic Smarty templates
  *
- * LONG
+ * This function searches for existing RSS feed template customizations. As long as a template
+ * with the same name as the $version variable exists, it will be emitted.
  *
  * @access public
- * @param
+ * @see serendipity_fetchEntries(), rss.php
+ * @param   array       A superarray of entries to output
+ * @param   string      The version/type of a RSS/Atom feed to display (atom1_0, rss2_0 etc)
+ * @param   boolean     If true, this is a comments feed. If false, it's an Entry feed.
+ * @param   boolean     Indicates if this feed is a fulltext feed (true) or only excercpt (false)
+ * @param   boolean     Indicates if E-Mail addresses should be shown (true) or hidden (false)
  * @return
  */
 function serendipity_printEntries_rss(&$entries, $version, $comments = false, $fullFeed = false, $showMail = true) {
diff --git a/include/functions_smarty.inc.php b/include/functions_smarty.inc.php
index 4644043..a993d9c 100644
--- a/include/functions_smarty.inc.php
+++ b/include/functions_smarty.inc.php
@@ -3,12 +3,12 @@
 # All rights reserved.  See LICENSE file for licensing details
 
 /**
- * SHORT
- *
- * LONG
+ * Fetch a list of trackbacks for an entry
  *
  * @access public
- * @param
+ * @param   int     The ID of the entry
+ * @param   string  How many trackbacks to show
+ * @param   boolean If true, also non-approved trackbacks will be shown 
  * @return
  */
 function serendipity_fetchTrackbacks($id, $limit = null, $showAll = false) {
@@ -33,12 +33,12 @@ function serendipity_fetchTrackbacks($id, $limit = null, $showAll = false) {
 }
 
 /**
- * SHORT
+ * Show trackbacks for an entry
  *
  * LONG
  *
  * @access public
- * @param
+ * @param   array       The superarray of trackbacks to display
  * @return
  */
 function serendipity_printTrackbacks($trackbacks) {
@@ -50,13 +50,13 @@ function serendipity_printTrackbacks($trackbacks) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Smarty: Fetch a smarty block and pass it on to Serendipity Templates
  *
  * @access public
- * @param
- * @return
+ * @param   string      The name of the block to parse data into ("COMMENTS" - virtual variable like {$COMMENTS})
+ * @param   string      The name of the template file to fetch. Only filename, the path is auto-detected
+ * @param   boolean     If true, the output of the smarty parser will be echoed instead of invisibly treated
+ * @return  string      The parsed HTML code
  */
 function &serendipity_smarty_fetch($block, $file, $echo = false) {
     global $serendipity;
@@ -68,26 +68,28 @@ function &serendipity_smarty_fetch($block, $file, $echo = false) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Smarty Modifier: Check if a string is not empty and prepend a prefix in that case. Else, leave empty
  *
  * @access public
- * @param
- * @return
+ * @param   string  The input string to check
+ * @param   string  The prefix to prepend, if $string is not empty
+ * @return  string  The return string
  */
 function serendipity_emptyPrefix($string, $prefix = ': ') {
     return (!empty($string) ? $prefix . htmlspecialchars($string) : '');
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Smarty Function: Be able to include the output of a sidebar plugin within a smarty template
  *
  * @access public
- * @param
- * @return
+ * @param   array       Smarty parameter input array:
+ *                          class: The classname of the plugin to show
+ *                          id: An ID of a plugin to show
+ *                          side: The side of a plugin to show (left|right|hidden)
+ *                          negate: Revert previous filters
+ * @param   object  Smarty object
+ * @return  string      The Smarty HTML response
  */
 function serendipity_smarty_showPlugin($params, &$smarty) {
     global $serendipity;
@@ -109,13 +111,20 @@ function serendipity_smarty_showPlugin($params, &$smarty) {
 }
 
 /**
- * SHORT
+ * Smarty Function: Be able to execute the hook of an event plugin and return its output
  *
- * LONG
+ * Listens to specific serendipity global variables:
+ *  $serendipity['skip_smarty_hooks'] - If TRUE, no plugins will be executed at all
+ *  $serendipity['skip_smarty_hook']  - Can be set to an array of plugin hooks to NOT execute
  *
  * @access public
- * @param
- * @return
+ * @param   array       Smarty parameter input array:
+ *                          hook: The name of the event hook
+ *                          hookAll: boolean whether unknown hooks shall be executed
+ *                          data: The $eventData to an event plugin
+ *                          addData: the $addData to an event plugin
+ * @param   object  Smarty object
+ * @return null
  */
 function serendipity_smarty_hookPlugin($params, &$smarty) {
     global $serendipity;
@@ -161,13 +170,13 @@ function serendipity_smarty_hookPlugin($params, &$smarty) {
 
 
 /**
- * SHORT
- *
- * LONG
+ * Smarty Function: Prints a list of sidebar plugins
  *
  * @access public
- * @param
- * @return
+ * @param   array       Smarty parameter input array:
+ *                          side: The plugin side to show (left|right|hidden)
+ * @param   object  Smarty object
+ * @return string       The HTML code of a plugin's output
  */
 function serendipity_smarty_printSidebar($params, &$smarty) {
     if ( !isset($params['side']) ) {
@@ -178,13 +187,13 @@ function serendipity_smarty_printSidebar($params, &$smarty) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Smarty Function: Get the full path to a template file
  *
  * @access public
- * @param
- * @return
+ * @param   array       Smarty parameter input array:
+ *                          file: The filename you want to include (any file within your template directry or the 'default' template if not found)
+ * @param   object  Smarty object
+ * @return  string      The requested filename with full path
  */
 function serendipity_smarty_getFile($params, &$smarty) {
     if ( !isset($params['file']) ) {
@@ -195,13 +204,14 @@ function serendipity_smarty_getFile($params, &$smarty) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Smarty Function: Get a permalink for an entry
  *
  * @access public
- * @param
- * @return
+ * @param   array       Smarty parameter input array:
+ *                          entry: $entry data to pull title etc. out of
+ *                          is_comments: Whether a permalink for a comment feed should be embedded
+ * @param   object  Smarty object
+ * @return string       The permalink
  */
 function serendipity_smarty_rss_getguid($params, &$smarty) {
     if ( !isset($params['entry']) ) {
@@ -217,12 +227,12 @@ function serendipity_smarty_rss_getguid($params, &$smarty) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Smarty Modifier: Format a timestamp
  *
  * @access public
- * @param
+ * @param   int     The timestamp to format (unix seconds)
+ * @param   string  The strftime() format options on how to format this string
+ * @param   boolean Shall timezone conversions be applied?
  * @return
  */
 function serendipity_smarty_formatTime($timestamp, $format, $useOffset = true) {
@@ -234,13 +244,14 @@ function serendipity_smarty_formatTime($timestamp, $format, $useOffset = true) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Smarty Function: Show comments to an entry
  *
  * @access public
- * @param
- * @return
+ * @param   array       Smarty parameter input array:
+ *                          entry: The $entry data
+ *                          mode: The default viewmode (threaded/linear)
+ * @param   object  Smarty object
+ * @return  string      The HTML code with the comments
  */
 function &serendipity_smarty_printComments($params, &$smarty) {
     global $serendipity;
@@ -273,12 +284,12 @@ function &serendipity_smarty_printComments($params, &$smarty) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Smarty Function: Show Trackbacks 
  *
  * @access public
- * @param
+ * @param   array       Smarty parameter input array:
+ *                          entry: The $entry data for the trackbacks
+ * @param   object  Smarty object
  * @return
  */
 function serendipity_smarty_printTrackbacks($params, &$smarty) {
@@ -291,12 +302,11 @@ function serendipity_smarty_printTrackbacks($params, &$smarty) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Smarty Prefilter: Replace constants to direkt $smarty.const. access
  *
  * @access public
- * @param
+ * @param   string  Template source content
+ * @param   object  Smarty object
  * @return
  */
 function &serendipity_replaceSmartyVars(&$tpl_source, &$smarty) {
@@ -305,13 +315,10 @@ function &serendipity_replaceSmartyVars(&$tpl_source, &$smarty) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Initialize the Smarty framework for use in Serendipity
  *
  * @access public
- * @param
- * @return
+ * @return null
  */
 function serendipity_smarty_init() {
     global $serendipity;
@@ -421,15 +428,11 @@ function serendipity_smarty_init() {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Purge compiled Smarty Templates
  *
  * @access public
- * @param
- * @return
+ * @return null
  */
-/* Nukes all Smarty compiled templates and cache */
 function serendipity_smarty_purge() {
     global $serendipity;
 
@@ -448,16 +451,16 @@ function serendipity_smarty_purge() {
 }
 
 /**
- * SHORT
+ * Shut down the Smarty Framework, output all parsed data
  *
- * LONG
+ * This function is meant to be used in embedded installations, like in Gallery.
+ * Function can be called from foreign applications. ob_start() needs to
+ * have been called before, and will be parsed into Smarty here
  *
  * @access public
- * @param
- * @return
+ * @param   string  The path to Serendipity
+ * @return null
  */
-/* Function can be called from foreign applications. ob_start() needs to
-  have been called before, and will be parsed into Smarty here */
 function serendipity_smarty_shutdown($serendipity_directory = '') {
 global $serendipity;
 
diff --git a/include/functions_trackbacks.inc.php b/include/functions_trackbacks.inc.php
index ec57532..d0b96ea 100644
--- a/include/functions_trackbacks.inc.php
+++ b/include/functions_trackbacks.inc.php
@@ -3,16 +3,11 @@
 # All rights reserved.  See LICENSE file for licensing details
 
 /**
- * SHORT
- *
- * LONG
+ * Check a HTTP response if it is a valid XML trackback response
  *
  * @access public
- * @param
- * @return
- */
-/**
- * validate trackback response
+ * @param   string  HTTP Response string
+ * @return  mixed   Boolean or error message
  */
 function serendipity_trackback_is_success($resp) {
     if (preg_match('@<error>(\d+)</error>@', $resp, $matches)) {
@@ -31,12 +26,11 @@ function serendipity_trackback_is_success($resp) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Perform a HTTP query for autodiscovering a pingback URL
  *
  * @access public
- * @param
+ * @param   string  (deprecated) The URL to try autodiscovery
+ * @param   string  The response of the original URL
  * @return
  */
 function serendipity_pingback_autodiscover($loc, $body) {
@@ -69,16 +63,12 @@ global $serendipity;
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Send a track/pingback ping
  *
  * @access public
- * @param
- * @return
- */
-/**
- * Send a trackback ping
+ * @param   string  The URL to send a trackback to
+ * @param   string  The XML data with the trackback contents
+ * @return  string  Reponse
  */
 function _serendipity_send($loc, $data) {
     global $serendipity;
@@ -118,13 +108,18 @@ function _serendipity_send($loc, $data) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Autodiscover a trackback location URL
  *
  * @access public
- * @param
- * @return
+ * @param   string  The HTML of the source URL
+ * @param   string  The source URL
+ * @param   string  The URL of our blog
+ * @param   string  The author of our entry
+ * @param   string  The title of our entry
+ * @param   string  The text of our entry
+ * @param   string  A comparsion URL
+ 
+ * @return string   Response
  */
 function serendipity_trackback_autodiscover($res, $loc, $url, $author, $title, $text, $loc2 = '') {
     if (!preg_match('@trackback:ping(\s*rdf:resource)?\s*=\s*["\'](https?:[^"\']+)["\']@i', $res, $matches)) {
@@ -167,13 +162,15 @@ function serendipity_trackback_autodiscover($res, $loc, $url, $author, $title, $
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Open a URL and autodetect contained ping/trackback locations
  *
  * @access public
- * @param
- * @return
+ * @param   string  The URL to autodetect/try
+ * @param   string  The URL to our blog
+ * @param   string  The author of our entry
+ * @param   string  The title of our entry
+ * @param   string  The body of our entry
+ * @return null
  */
 function serendipity_reference_autodiscover($loc, $url, $author, $title, $text) {
 global $serendipity;
@@ -236,13 +233,15 @@ global $serendipity;
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Receive a trackback
  *
  * @access public
- * @param
- * @return
+ * @param   int     The ID of our entry
+ * @param   string  The title of the foreign blog
+ * @param   string  The URL of the foreign blog
+ * @param   string  The name of the foreign blog
+ * @param   string  The excerpt text of the foreign blog
+ * @return true
  */
 function add_trackback ($id, $title, $url, $name, $excerpt) {
     global $serendipity;
@@ -269,13 +268,12 @@ function add_trackback ($id, $title, $url, $name, $excerpt) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Receive a pingback
  *
  * @access public
- * @param
- * @return
+ * @param   int     The entryid to receive a pingback for
+ * @param   string  The foreign postdata to add
+ * @return boolean
  */
 function add_pingback ($id, $postdata) {
     global $serendipity;
@@ -295,29 +293,20 @@ function add_pingback ($id, $postdata) {
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Create an excerpt for a trackback to send
  *
  * @access public
- * @param
- * @return
- */
-/**
- * Cut text
+ * @param   string  Input text
+ * @return  string  Output text
  */
 function serendipity_trackback_excerpt($text) {
     return substr(strip_tags($text), 0, 255);
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Report success of a trackback
  *
  * @access public
- * @param
- * @return
  */
 function report_trackback_success () {
 print '<?xml version="1.0" encoding="iso-8859-1"?>' . "\n";
@@ -329,13 +318,9 @@ SUCCESS;
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Report failure of a trackback
  *
  * @access public
- * @param
- * @return
  */
 function report_trackback_failure () {
 print '<?xml version="1.0" encoding="iso-8859-1"?>' . "\n";
@@ -348,13 +333,9 @@ FAILURE;
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Return success of a pingback
  *
  * @access public
- * @param
- * @return
  */
 function report_pingback_success () {
 print '<?xml version="1.0"?>' . "\n";
@@ -370,13 +351,9 @@ SUCCESS;
 }
 
 /**
- * SHORT
- *
- * LONG
+ * Return failure of a pingback
  *
  * @access public
- * @param
- * @return
  */
 function report_pingback_failure () {
 print '<?xml version="1.0"?>' . "\n";
@@ -390,17 +367,18 @@ FAILURE;
 }
 
 /**
- * SHORT
+ * Search through link body, and automagically send a trackback ping.
  *
- * LONG
+ * This is the trackback starter function that searches your text and sees if any
+ * trackback URLs are in there
  *
  * @access public
- * @param
+ * @param   int     The ID of our entry
+ * @param   string  The author of our entry
+ * @param   string  The title of our entry
+ * @param   string  The text of our entry
  * @return
  */
-/**
- * search through link body, and automatically send a trackback ping.
- */
 function serendipity_handle_references($id, $author, $title, $text) {
     global $serendipity;
 
diff --git a/include/lang.inc.php b/include/lang.inc.php
index ce89098..68d2b4f 100644
--- a/include/lang.inc.php
+++ b/include/lang.inc.php
@@ -31,16 +31,15 @@ if (!defined('serendipity_MB_LOADED') && defined('serendipity_LANG_LOADED')) {
     }
 
 /**
- * SHORT
+ * Wrapper for multibyte string operations
  *
- * LONG
+ * Multibyte string functions wrapper:
+ * strlen(), strpos(), strrpos(), strtolower(), strtoupper(), substr(), ucfirst()
  *
  * @access public
- * @param
- * @return
+ * @param   mixed       Any input array, dynamically evaluated for best emulation
+ * @return mixed
  */
-    // Multibyte string functions wrapper:
-    // strlen(), strpos(), strrpos(), strtolower(), strtoupper(), substr(), ucfirst()
     function serendipity_mb() {
         static $mbstring = null;
 
diff --git a/include/plugin_api.inc.php b/include/plugin_api.inc.php
index aadf36d..07e5245 100644
--- a/include/plugin_api.inc.php
+++ b/include/plugin_api.inc.php
@@ -30,13 +30,10 @@ include_once S9Y_INCLUDE_PATH . 'include/functions.inc.php';
 class serendipity_plugin_api {
 
 /**
- * SHORT
- *
- * LONG
+ * Register the default list of plugins for installation.
  *
  * @access public
- * @param
- * @return
+ * @return null
  */
     function register_default_plugins()
     {
@@ -123,13 +120,11 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Removes a plugin by it's instance name
  *
  * @access public
- * @param
- * @return
+ * @param   string  The name of the plugin id ("serendipity_plugin_xxx:1232132fsdf")
+ * @return null
  */
     function remove_plugin_instance($plugin_instance_id)
     {
@@ -152,13 +147,12 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Removes an empty plugin configuration value
  *
  * @access public
- * @param
- * @return
+ * @param   string  The name of the plugin id ("serendipity_plugin_xxx:1232132fsdf")
+ * @param   array   An array of configuration item names
+ * @return null
  */
     function remove_plugin_value($plugin_instance_id, $where)
     {
@@ -175,15 +169,15 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
+ * Retrieve a list of available plugin classes
  *
- * LONG
+ * This function searches through all directories and loaded internal files and tries
+ * to detect the serendipity plugins.
  *
  * @access public
- * @param
+ * @param   boolean     If true, only event plugins will be searched. If false, sidebar plugins will be searched.
  * @return
  */
-    /* Retrieves a list of available plugins */
     function &enum_plugin_classes($event_only = false)
     {
         global $serendipity;
@@ -229,12 +223,13 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Traverse a specific directory and search if a serendipity plugin exists there.
  *
  * @access public
- * @param
+ * @param   string      The path to start from (usually '.')
+ * @param   array       A referenced array of currently found classes
+ * @param   boolean     If true, only event plugins will be searched. If false, only sidebar plugins will be searched.
+ * @param   string      The maindir where we started searching from [for recursive use]
  * @return
  */
     function traverse_plugin_dir($ppath, &$classes, $event_only, $maindir = '') {
@@ -300,13 +295,11 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Returns a list of currently installed plugins
  *
  * @access public
- * @param
- * @return
+ * @param   string  The filter for plugins (left|right|hidden|event)
+ * @return  array   The list of plugins
  */
     function get_installed_plugins($filter = '*') {
         $plugins = serendipity_plugin_api::enum_plugins($filter);
@@ -322,15 +315,15 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Searches for installed plugins based on specific conditions
  *
  * @access public
- * @param
- * @return
+ * @param   string  The filter for plugins (left|right|hidden|event)
+ * @param   boolean If true, the filtering logic will be reversed an all plugins that are NOT part of the filter will be returned
+ * @param   string  Filter by a specific classname (like 'serendipity_plugin_archives'). Can take SQL wildcards.
+ * @param   string  Filter by a specific plugin instance id
+ * @return  array   Returns the associative array of found plugins in the database
  */
-    /* Retrieves a list of plugin instances */
     function enum_plugins($filter = '*', $negate = false, $classname = null, $id = null)
     {
         global $serendipity;
@@ -364,15 +357,13 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Count the number of plugins to which the filter criteria matches
  *
  * @access public
- * @param
- * @return
+ * @param   string  The filter for plugins (left|right|hidden|event)
+ * @param   boolean If true, the filtering logic will be reversed an all plugins that are NOT part of the filter will be evaluated
+ * @return  int     Number of plugins that were found.
  */
-    /* Retrieves a list of plugin instances */
     function count_plugins($filter = '*', $negate = false)
     {
         global $serendipity;
@@ -396,13 +387,13 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Detect the filename to use for a specific plugin
  *
  * @access public
- * @param
- * @return
+ * @param   string  The name of the plugin ('serendipity_event_archive')
+ * @param   string  The path to the plugin file (if empty, the current path structure will be used.)
+ * @param   string  If an instance ID is passed this means, the plugin to be loaded is internally available
+ * @return  string  Returns the filename to include for a specific plugin
  */
     function includePlugin($name, $pluginPath = '', $instance_id = '') {
         global $serendipity;
@@ -427,13 +418,12 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Returns the plugin class name by a plugin instance ID
  *
  * @access public
- * @param
- * @return
+ * @param   string      The ID of a plugin
+ * @param   boolean     If true, the plugin is a internal plugin (prefixed with '@')
+ * @return  string      The classname of the plugin
  */
     function getClassByInstanceID($instance_id, &$is_internal) {
         $instance = explode(':', $instance_id);
@@ -449,13 +439,13 @@ class serendipity_plugin_api {
     }
     
 /**
- * SHORT
- *
- * LONG
+ * Auto-detect a plugin and see if the file information is given, and if not, detect it.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The ID of a plugin to load
+ * @param   string      A reference variable that will hold the class name of the plugin (do not pass manually)
+ * @param   string      A reference variable that will hold the path to the plugin (do not pass manually)
+ * @return  string      Returns the filename of a plugin to load
  */
     /* Probes for the plugin filename */
     function probePlugin($instance_id, &$class_name, &$pluginPath) {
@@ -497,15 +487,15 @@ class serendipity_plugin_api {
     }
     
 /**
- * SHORT
- *
- * LONG
+ * Instantiates a plugin class
  *
  * @access public
- * @param
+ * @param   string      The ID of the plugin to load
+ * @param   int         The owner of the plugin (can be autodetected)
+ * @param   string      The path to a plugin (can be autodetected)
+ * @param   string      The filename of a plugin (can be autodetected)
  * @return
  */
-    /* Creates an instance of a named plugin */
     function &load_plugin($instance_id, $authorid = null, $pluginPath = '', $pluginFile = null) {
         global $serendipity;
 
@@ -546,13 +536,13 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Gets cached properties/information about a specific plugin, auto-loads a cache of all plugins
  *
  * @access public
- * @param
- * @return
+ * @param   string      The filename of the plugin to get information about
+ * @param   array       A referenced array that holds information about the plugin instance (self::load_plugin() response)
+ * @param   type        The type of the plugin (local|spartacus|...)
+ * @return  array       Information about the plugin
  */
     function &getPluginInfo(&$pluginFile, &$class_data, $type) {
         global $serendipity;
@@ -594,12 +584,14 @@ class serendipity_plugin_api {
     }
     
 /**
- * SHORT
- *
- * LONG
+ * Set cache information about a plugin
  *
  * @access public
- * @param
+ * @param   mixed       Either an plugin object or a plugin information array that holds the information about the plugin
+ * @param   string      The filename of the plugin
+ * @param   object      The property bag object bundled with the plugin
+ * @param   array       Previous/additional information about the plugin
+ * @param   string      The location/type of a plugin (local|spartacus)
  * @return
  */
     function &setPluginInfo(&$plugin, &$pluginFile, &$bag, &$class_data, $pluginlocation = 'local') {
@@ -696,12 +688,12 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Moves a sidebar plugin to a different side or up/down
  *
  * @access public
- * @param
+ * @param   string  The instance ID of a plugin
+ * @param   string  The new placement of a plugin (left|right|hidden)
+ * @param   string  A new sort order for the plugin
  * @return
  */
     function update_plugin_placement($name, $placement, $order=null)
@@ -726,12 +718,11 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Updates the ownership information about a plugin
  *
  * @access public
- * @param
+ * @param   string  The instance ID of the plugin
+ * @param   int     The ID of the new author owner of the plugin
  * @return
  */
     function update_plugin_owner($name, $authorid)
@@ -753,13 +744,15 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Get a list of Sidebar plugins and pass them to Smarty
  *
  * @access public
- * @param
- * @return
+ * @param   string      The side of plugins to show (left/right/hidden)
+ * @param   string      deprecated: Indicated which wrapping HTML element to use for plugins
+ * @param   boolean     Indicates whether only all plugins should be shown that are not in the $side list
+ * @param   string      Only show plugins of this plugin class
+ * @param   string      Only show a plugin with this instance ID
+ * @return  string      Smarty HTML output
  */
     function generate_plugins($side, $tag = '', $negate = false, $class = null, $id = null)
     {
@@ -822,13 +815,12 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Gets the title of a plugin to be shown in plugin overview
  *
  * @access public
- * @param
- * @return
+ * @param   object      The plugin object
+ * @param   string      The default title, if none was configured
+ * @return  string      The title of the plugin
  */
     function get_plugin_title(&$plugin, $default_title = '')
     {
@@ -861,28 +853,25 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
+ * Check if a plugin is an event plugin
  *
- * LONG
+ * Refactoring: decompose conditional
  *
  * @access public
- * @param
- * @return
+ * @param   string  Name of a plugin
+ * @return  boolean
  */
-    /* conditional to see if the named plugin is an event plugin
-        Refactoring: decompose conditional */
     function is_event_plugin($name) {
         return (strstr($name, '_event_'));
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Prepares a cache of all event plugins and load them in queue so that they can be fetched
  *
  * @access public
- * @param
- * @return
+ * @param  mixed    If set to a string, a certain event plugin cache object will be returned by this function
+ * @param  boolean  If set to true, the list of cached event plugins will be refreshed
+ * @return mixed    Either returns the whole list of event plugins, or only a specific instance
  */
     function &get_event_plugins($getInstance = false, $refresh = false) {
         static $event_plugins;
@@ -927,13 +916,16 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
+ * Executes a specific Eventhook
  *
- * LONG
+ * If you want to temporarily block any event plugins, you can set $serendipity['no_events'] before
+ * this method call.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The name of the event to hook on to
+ * @param   mixed       May contain any type of variables that are passed by reference to an event plugin
+ * @param   mixed       May contain any type of variables that are passed to an event plugin
+ * @return true
  */
     function hook_event($event_name, &$eventData, $addData = null) {
         global $serendipity;
@@ -965,13 +957,11 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Checks if a specific plugin instance is already installed
  *
  * @access public
- * @param
- * @return
+ * @param   string      A name (may contain wildcards) of a plugin class to check
+ * @return  boolean     True if a plugin was found
  */
     function exists($instance_id) {
         global $serendipity;
@@ -990,13 +980,13 @@ class serendipity_plugin_api {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Install a new plugin by ensuring that it does not already exist
  *
  * @access public
- * @param
- * @return
+ * @param   string      The classname of the plugin
+ * @param   int         The new owner author
+ * @param   boolean     Indicates if the plugin is an event plugin
+ * @return  object      Returns the plugin object or false, if failure
  */
     function &autodetect_instance($plugin_name, $authorid, $is_event_plugin = false) {
         if ($is_event_plugin) {
@@ -1031,13 +1021,12 @@ class serendipity_property_bag {
     var $name       = null;
 
 /**
- * SHORT
- *
- * LONG
+ * Adds a property value to the bag
  *
  * @access public
- * @param
- * @return
+ * @param   string  The name of the property
+ * @param   mixed   The value of a property
+ * @return null
  */
     function add($name, $value)
     {
@@ -1045,13 +1034,11 @@ class serendipity_property_bag {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Returns a property value of a bag
  *
  * @access public
- * @param
- * @return
+ * @param   string  Name of property to fetch
+ * @return  mixed   The value of the property
  */
     function &get($name)
     {
@@ -1059,13 +1046,11 @@ class serendipity_property_bag {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Check if a specific property name is already set
  *
  * @access public
- * @param
- * @return
+ * @param   string  Name of the property to check
+ * @return  boolean True, if already set.
  */
     function is_set($name)
     {
@@ -1077,6 +1062,7 @@ class serendipity_property_bag {
     }
 }
 
+/* A core plugin, with methods that both event and sidebar plugins share */
 class serendipity_plugin {
     var $instance      = null;
     var $protected     = false;
@@ -1086,16 +1072,14 @@ class serendipity_plugin {
     var $title         = null;
 
 /**
- * SHORT
+ * The constructor of a plugin
  *
- * LONG
+ * Needs to be implemented by your own class.
+ * Be sure to call this method from your derived classes constructors,
+ * otherwise your config data will not be stored or retrieved correctly
  *
  * @access public
- * @param
- * @return
- */
-/* Be sure to call this method from your derived classes constructors,
- * otherwise your config data will not be stored or retrieved correctly
+ * @return true
  */
     function serendipity_plugin($instance)
     {
@@ -1103,16 +1087,13 @@ class serendipity_plugin {
     }
 
 /**
- * SHORT
+ * Perform install routines
  *
- * LONG
+ * Called by Serendipity when the plugin is first installed.
+ * Can be used to install database tables etc.
  *
  * @access public
- * @param
- * @return
- */
-/* Called by Serendipity when the plugin is first installed.
- * Can be used to install database tables etc.
+ * @return true
  */
     function install()
     {
@@ -1120,16 +1101,14 @@ class serendipity_plugin {
     }
 
 /**
- * SHORT
+ * Perform uninstall routines
  *
- * LONG
+ * Called by Serendipity when the plugin is removed/uninstalled.
+ * Can be used to drop installed database tables etc.
  *
  * @access public
- * @param
- * @return
- */
-/* Called by Serendipity when the plugin is removed/uninstalled.
- * Can be used to drop installed database tables etc.
+ * @param  object   A property bag object
+ * @return true
  */
     function uninstall(&$propbag)
     {
@@ -1137,17 +1116,15 @@ class serendipity_plugin {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * The introspection function of a plugin, to setup properties
  *
- * @access public
- * @param
- * @return
- */
-/* Called by serendipity when it wants to display information
+ * Called by serendipity when it wants to display information
  * about your plugin.
  * You need to override this method in your child class.
+ *
+ * @access public
+ * @param   object  A property bag object you can manipulate
+ * @return true
  */
     function introspect(&$propbag)
     {
@@ -1168,15 +1145,9 @@ class serendipity_plugin {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Introspection of a plugin configuration item
  *
- * @access public
- * @param
- * @return
- */
-/* Called by serendipity when it wants to display the configuration
+ * Called by serendipity when it wants to display the configuration
  * editor for your plugin.
  * $name is the name of a configuration item you added in
  * your instrospect method.
@@ -1185,6 +1156,11 @@ class serendipity_plugin {
  * configuration option.
  * You need to override this method in your child class if
  * you have configuration options.
+ *
+ * @access public
+ * @param   string      Name of the config item
+ * @param   object      A property bag object you can store the configuration in
+ * @return
  */
     function introspect_config_item($name, &$propbag)
     {
@@ -1192,15 +1168,16 @@ class serendipity_plugin {
     }
 
 /**
- * SHORT
+ * Validate plugin configuration options.
  *
- * LONG
+ * Called from Plugin Configuration manager. Can be extended by your own plugin, if you need.
  *
  * @access public
- * @param
+ * @param   string      Name of the config item to validate
+ * @param   object      Property bag of the config item
+ * @param   value       The value of a config item
  * @return
  */
-    /* Called to validate a plugin option */
     function validate($config_item, &$cbag, &$value) {
         static $pattern_mail  = '([\.\-\+~@_0-9a-z]+?)';
         static $pattern_url   = '([@!=~\?:&;0-9a-z#\.\-_\/]+?)';
@@ -1267,20 +1244,18 @@ class serendipity_plugin {
     }
     
 /**
- * SHORT
+ * Output plugin's contents (Sidebar plugins)
  *
- * LONG
- *
- * @access public
- * @param
- * @return
- */
-/* Called by serendipity when it wants your plugin to display itself.
+ * Called by serendipity when it wants your plugin to display itself.
  * You need to set $title to be whatever text you want want to
  * appear in the item caption space.
  * Simply echo/print your content to the output; serendipity will
  * capture it and make things work.
  * You need to override this method in your child class.
+ *
+ * @access public
+ * @param   string       The referenced varaiable that holds the sidebar title of your plugin.
+ * @return null
  */
     function generate_content(&$title)
     {
@@ -1289,15 +1264,14 @@ class serendipity_plugin {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Get a config value of the plugin
  *
  * @access public
- * @param
- * @return
+ * @param   string  Name of the config value to fetch
+ * @param   mixed   The default value of a configuration item, if not set
+ * @param   boolean If true, the default value will only be set if the plugin config item was not set.
+ * @return  mixed   The value of the config item
  */
-    /* Fetches a configuration value for this plugin */
     function get_config($name, $defaultvalue = null, $empty = true)
     {
         $_res = serendipity_get_config_var($this->instance . '/' . $name, $defaultvalue, $empty);
@@ -1320,12 +1294,11 @@ class serendipity_plugin {
     }
 
 /**
- * SHORT
- *
- * LONG
+ * Sets a configuration value for a plugin
  *
  * @access public
- * @param
+ * @param   string  Name of the plugin configuration item
+ * @param   string  Value of the plugin configuration item
  * @return
  */
     function set_config($name, $value)
@@ -1336,17 +1309,14 @@ class serendipity_plugin {
     }
 
 /**
- * SHORT
+ * Garbage Collection
  *
- * LONG
+ * Called by serendipity after insertion of a config item. If you want to kick out certain
+ * elements based on contents, create the corresponding function here.
  *
  * @access public
- * @param
- * @return
+ * @return true
  */
-    /* Called by serendipity after insertion of a config item. If you want to kick out certain
-     * elements based on contents, create the corresponding function here.
-     */
     function cleanup()
     {
         // Cleanup. Remove all empty configs on SAVECONF-Submit.
@@ -1355,13 +1325,14 @@ class serendipity_plugin {
     }
 
 /**
- * SHORT
+ * Auto-Register dependencies of a plugin
  *
- * LONG
+ * This method evaluates the "dependencies" member variable to check which plugins need to be installed.
  *
  * @access public
- * @param
- * @return
+ * @param   boolean     If true, a depending plugin will be removed when this plugin is uninstalled
+ * @param   int         The owner id of the current plugin
+ * @return true
  */
     function register_dependencies($remove = false, $authorid = '0')
     {
@@ -1407,22 +1378,20 @@ class serendipity_plugin {
     }
 }
 
-class serendipity_event extends serendipity_plugin {
 /* Events can be called on several occasions when s9y performs an action.
  * One or multiple plugin can be registered for each of those hooks.
  */
+class serendipity_event extends serendipity_plugin {
 
 /**
- * SHORT
+ * The class constructor
  *
- * LONG
+ * Be sure to call this method from your derived classes constructors,
+ * otherwise your config data will not be stored or retrieved correctly
  *
  * @access public
- * @param
+ * @param   string      The instance name
  * @return
- */
-/* Be sure to call this method from your derived classes constructors,
- * otherwise your config data will not be stored or retrieved correctly
  */
     function serendipity_event($instance)
     {
@@ -1430,13 +1399,16 @@ class serendipity_event extends serendipity_plugin {
     }
 
 /**
- * SHORT
+ * Gets a reference to an $entry / $eventData array pointer, interacting with Cache-Options
  *
- * LONG
+ * This function is used by specific event plugins that require to properly get a reference
+ * to the 'extended' or 'body' field of an entry superarray. If they would immediately operate
+ * on the 'body' field, it might get overwritten by other plugins later on.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The fieldname to get a reference for
+ * @param   array       The entry superarray to get the reference from
+ * @return  array       The value of the array for the fieldname (reference)
  */
     function &getFieldReference($fieldname = 'body', &$eventData) {
         // Get a reference to a content field (body/extended) of
@@ -1472,13 +1444,17 @@ class serendipity_event extends serendipity_plugin {
     }
 
 /**
- * SHORT
+ * Main logic for making a plugin "listen" to an event
  *
- * LONG
+ * This method is called by the main plugin API for every event, that is executed.
+ * You need to implement each actions that shall be performed by your plugin here.
  *
  * @access public
- * @param
- * @return
+ * @param   string      The name of the executed event
+ * @param   object      A property bag for the current plugin
+ * @param   mixed       Any referenced event data from the serendipity_plugin_api::hook_event() function
+ * @param   mixed       Any additional data from the hook_event call
+ * @return true
  */
     function event_hook($event, &$bag, &$eventData, $addData = null) {
         // Define event hooks here, if you want you plugin to execute those instead of being a sidebar item.