--- a/common-functions.inc	Thu Oct 11 20:36:24 2012 +0200
+++ b/common-functions.inc	Thu Oct 11 22:11:33 2012 +0200
@@ -5,11 +5,21 @@
  */
 include_once 'CacheTimeCheck.inc';
 
+/// @cond
 $baseDir = dirname(__FILE__);
 
 $cache = CacheTimeCheck::instance(__FILE__);
 $cache->includeOnce('StatusCodes.inc', $baseDir);
+/// @endcond
 
+/**
+ * Generates a representation for an array of key => value pairs
+ *
+ * @note Behaviour is undefined if value is a composite structure.
+ *
+ * @param $map the input array
+ * @return a string representation that may be eval'ed
+ */
 function repMapString($map)
 {
   $opt = 'array(';
@@ -28,12 +38,29 @@
   return $opt;
 }
 
+/**
+ * Get the location on the server where the top level script is
+ * located
+ *
+ * @return directory
+ */
 function basePath()
 {
   $l = strrpos($_SERVER['SCRIPT_FILENAME'], $_SERVER['SCRIPT_NAME']);
   return substr($_SERVER['SCRIPT_FILENAME'], 0, $l);
 }
 
+/**
+ * Loads a file
+ *
+ * @param $sFilename name of the file to load
+ * @param $sCharset the character encoding of the file
+ *
+ * @todo make this function throw instead of returning codes
+ *
+ * @return the contents of the file, or a status code (-3 if file does
+ * not exists, if file could not be opened -2)
+ */
 function loadFile($sFilename, $sCharset = 'UTF-8')
 {
   if (floatval(phpversion()) >= 4.3) {
@@ -61,6 +88,12 @@
   return $sData;
 }
 
+/**
+ * Generate a status page and exit
+ *
+ * @param $errorText the text to be displayed in the body
+ * @param $errorCode the status code to be served
+ */
 function errorPage($errorText, $errorCode = 403)
 {
   header(StatusCodes::httpHeaderFor($errorCode));
@@ -68,6 +101,16 @@
   exit;
 }
 
+/**
+ * Generates an URL for the specified parameters
+ *
+ * @param $urlParams an associative array of the values already set
+ * @param $keys a set of values to override $urlParams
+ *
+ * @param $nonQueryParams a list of keys, where values should be in
+ * the URL, rather than the query part, note that the order is
+ * important
+ */
 function genUrl($urlParams, $keys = array(), $nonQueryParams = array()) {
   $out = '';
   $first = 1;
@@ -100,6 +143,15 @@
   return $out;
 }
 
+/**
+ * Retrieves a single subelement
+ * @throw Exception if number of elements are different from 1
+ *
+ * @todo Throw more specific exception
+ *
+ * @param $obj the xml element to search in
+ * @param $name the name of the element to search for
+ */
 function getElementByTagName($obj, $name) {
   $elems = $obj->getElementsByTagName($name);
   if ($elems->length != 1) {
@@ -109,31 +161,42 @@
   return $elem;
 }
 
-function getXmlContent($node)
-{
-  $text = $node->ownerDocument->saveXml($node);
-  $pattern = "/^<" . $node->tagName."[^>]*>/is";
-  $text = preg_replace($pattern, '' , $text);
-  $pattern = '/<\/' . $node->tagName . '[^>]*>$/is';
-  $text = preg_replace($pattern, '' , $text);
-
-  return $text;
-}
-
+/**
+ * Checks if one string start with another string
+ *
+ * @param $haystack the string to search
+ * @param $needle the string to search for
+ *
+ * @return bool if match
+ */
 function startswith($haystack, $needle)
 {
     return strpos($haystack, $needle) === 0;
 }
 
+/**
+ * Checks if one string ends with another string
+ *
+ * @param $haystack the string to search
+ * @param $needle the string to search for
+ *
+ * @return bool if match
+ */
 function endsWith($haystack, $needle)
 {
   $l = strlen($haystack) - strlen($needle);
   return strrpos($haystack, $needle) === $l;
 }
 
+/**
+ * Queries a URL for headers
+ *
+ * @param $url the url to query
+ * @return an associative array of all headers returned
+ */
 function getHeaders($url)
 {
-  $response = http_head($url, array("timeout"=>1), $info);
+  $response = http_head($url, array("timeout" => 1), $info);
   $headers = array();
   $str = explode("\n", $response);
   foreach($str as $kv) {
@@ -147,6 +210,12 @@
   return $headers;
 }
 
+/**
+ * Generates the query part of an URI
+ *
+ * @param $opts an associative array of options
+ * @return a string that can be used for the query part of an URI
+ */
 function opttostring($opts)
 {
   $str = '';