fixes #16

* all PHP code is documented
 * admin/scripts/*php is added to apidoc and gettext generation in Makefile

Makefile

@@ -26,6 +26,7 @@
 VERSION := 0.2
 PROJECT := davadmin
 SRCFILES := $(wildcard admin/*.php)
+SRCFILES += $(wildcard admin/scripts/*.php)
 JSFILES := admin/scripts/autocomplete.js admin/scripts/directories.js \
   admin/scripts/users.js
 APISRC := $(shell echo $(SRCFILES) | sed 's/ /,/g' )

admin/i18n.inc.php

@@ -1,6 +1,7 @@
 <?php
 /**
- * Internationalization code for DAVAdmin.
+ * Internationalization code for DAVAdmin. Some ideas where taken from
+ * Joomla CMS http://www.joomla.org/.
  *
  * @author Jan Dittberner <jan@dittberner.info>
  * @version $Id$
@@ -28,7 +29,11 @@
  */
 
 /**
- * Gets the language data.
+ * Gets the language data for supported languages.
+ *
+ * @return array associative array of language descriptions at index 0
+ * and associative array of language to default country mappings at
+ * index 1
  */
 function get_language_data() {
   static $supportedLanguages = array();
@@ -48,6 +53,17 @@ function get_language_data() {
   return array($supportedLanguages, $defaultCountry);
 }
 
+/**
+ * Sets the locale for the given LC_* constant in $category to $locale
+ * or a matching replacement.
+ *
+ * @param int $category one of the LC_* constants that PHP's setlocale
+ * function accepts
+ * @param string $locale locale name with or without country
+ * specification and with or without character set name
+ * @return string|boolean the locale actually set or FALSE if no
+ * locale could be set at all
+ */
 function _setlocale($category, $locale) {
   if (($ret = setlocale($category, $locale)) !== false) {
     return $ret;
@@ -77,10 +93,20 @@ function _setlocale($category, $locale) {
       return $ret;
     }
   }
-  echo "unable to select a valid locale code";
   return false;
 }
 
+/**
+ * Gets a supported language code. If $fallback is true en_US is
+ * returned as a last resort.
+ *
+ * @param string $code the language code which should be tested
+ * @param boolean $fallback if set to true (default) always return a
+ * valid language code
+ * @return string|boolean language code with country specification or
+ * false if $fallback is set to false and language code is not
+ * supported
+ */
 function _get_supported_language_code($code, $fallback = true) {
   static $supportedLanguages;
   static $defaultCountry;
@@ -107,6 +133,12 @@ function _get_supported_language_code($code, $fallback = true) {
   }
 }
 
+/**
+ * Negotiate the locale based on the value of
+ * $_SERVER['HTTP_ACCEPT_LANGUAGE'].
+ *
+ * @return string language code string or null
+ */
 function _http_negotiate_locale() {
   $accepted = $_SERVER['HTTP_ACCEPT_LANGUAGE'];
   if (!empty($accepted)) {
@@ -120,15 +152,19 @@ function _http_negotiate_locale() {
   return null;
 }
 
+// start the session
 session_start();
 $project = "davadmin";
 
+// set the language based on a GET-Parameter.
 if (isset($_GET["language"])) {
   $languageCode = _get_supported_language_code($_GET["language"], false);
   if (isset($languageCode)) {
     $_SESSION["language"] = $languageCode;
   }
 }
+// if the current session has a language use it, negotiate from
+// HTTP-Header otherwise
 if ($_SESSION["language"]) {
   $language = $_SESSION["language"];
 } else {
@@ -138,11 +174,14 @@ if ($_SESSION["language"]) {
 putenv(sprintf("LANG=%s", $_SESSION["language"]));
 putenv(sprintf("LANGUAGE=%s", $_SESSION["language"]));
 $_SESSION["locale"] = _setlocale(LC_ALL, $_SESSION["language"]);
+// bind text domain for normal code
 bindtextdomain($project,
                realpath(dirname(__FILE__) . DIRECTORY_SEPARATOR .
                         ".." . DIRECTORY_SEPARATOR . "po"));
+// bind text domain for JavaScript code
 bindtextdomain($project . "js",
                realpath(dirname(__FILE__) . DIRECTORY_SEPARATOR .
                         ".." . DIRECTORY_SEPARATOR . "po"));
+// set the default text domain to project name
 textdomain($project);
 ?>

admin/scripts/i18n.php

@@ -5,7 +5,7 @@
  * @author Jan Dittberner <jan@dittberner.info>
  * @version $Id$
  * @license GPL
- * @package DAVAdmin
+ * @package DAVAdmin::JavaScript
  *
  * Copyright (c) 2007 Jan Dittberner
  *
@@ -29,6 +29,7 @@
 
 /** Include the internationalization code. */
 require_once(".." . DIRECTORY_SEPARATOR . "i18n.inc.php");
+
 textdomain("davadminjs");
 
 $translatable = file(realpath(implode(DIRECTORY_SEPARATOR,

admin/shared.inc.php

@@ -30,6 +30,12 @@
 /** Include common internationalization code. */
 require_once("i18n.inc.php");
 
+/**
+ * Create a server error with HTTP status code 500 and end script
+ * execution.
+ *
+ * @param string $message error message
+ */
 function _server_error($message) {
   header('HTTP/1.0 500 Internal Server Error');
   header('Status: 500 Internal Server Error');

admin/users.php

@@ -34,7 +34,7 @@ include_once('common.inc.php');
  * Gets the names of the given users's groups from the group file.
  *
  * @param string $username user name
- * @return array of group names
+ * @return array array of group names
  * @access private
  */
 function _getGroupNames($username) {
@@ -57,7 +57,7 @@ function _getGroupNames($username) {
  * Gets XML encoded data for a user.
  * 
  * @param int $uid user id
- * @return XML string
+ * @return string XML string
  */
 function getUserData($uid) {
   if  (!(is_numeric($uid) && array_key_exists($uid, $GLOBALS['namemap']))) {
@@ -77,7 +77,7 @@ function getUserData($uid) {
  * Gets XML encoded data for a deleted user.
  *
  * @param int $uid user id
- * @return XML string
+ * @return string XML string
  */
 function getDeletedUserData($uid) {
   if  (!is_numeric($uid)) {
@@ -92,7 +92,8 @@ function getDeletedUserData($uid) {
  * @param array &$userdata reference to an user data array
  * @param boolean $forinsert if this is true the check skips field
  * that will be created during insert
- * @return an array with validation error messages or an empty array
+ * @return array an array with validation error messages or an empty
+ * array
  */
 function validateUserData(&$userdata, $forinsert) {
   $errormsgs = array();