From f6be78bdcfb0b20b750da8c014fa3a0e25ff3aaa Mon Sep 17 00:00:00 2001
From: Jan Dittberner <jan@dittberner.info>
Date: Sun, 2 Dec 2007 22:11:59 +0000
Subject: [PATCH] addresses #16  * api documentation finished for
 common.inc.php and directories.php

---
 Makefile              |  4 ++--
 admin/common.inc.php  | 32 ++++++++++++++++++++++++++++----
 admin/directories.php | 18 +++++++++---------
 3 files changed, 39 insertions(+), 15 deletions(-)

diff --git a/Makefile b/Makefile
index 1e26fba..a363f0f 100644
--- a/Makefile
+++ b/Makefile
@@ -28,7 +28,7 @@ PROJECT := davadmin
 SRCFILES := $(wildcard admin/*.php)
 JSFILES := admin/scripts/autocomplete.js admin/scripts/directories.js \
   admin/scripts/users.js
-APISRC := $(SRCFILES:,= )
+APISRC := $(shell echo $(SRCFILES) | sed 's/ /,/g' )
 TEMPDIR := $(shell mktemp -t -d davadmin.XXXXXXXXXX)
 XSRCFILES := $(patsubst %,$(TEMPDIR)/%,$(SRCFILES))
 XJSFILES := $(patsubst %,$(TEMPDIR)/%,$(JSFILES))
@@ -115,7 +115,7 @@ $(TEMPDIR)/delete:
 .PHONY: apidoc
 apidoc:
 	if [ -d apidoc ]; then rm -r apidoc; fi
-	phpdoc -f $(APISRC) -t apidoc --undocumentedelements on -s
+	phpdoc -ue on -f $(APISRC) -t apidoc -s
 
 .PHONY: clean distclean
 clean: $(TEMPDIR)/delete
diff --git a/admin/common.inc.php b/admin/common.inc.php
index 3aba89f..341f89d 100644
--- a/admin/common.inc.php
+++ b/admin/common.inc.php
@@ -65,14 +65,20 @@ if (!is_dir($compile_dir)) {
 }
 $smarty->compile_dir = $compile_dir;
 
-/** Handle invalid requests to the application. */
+/**
+ * Handle invalid requests to the application. Execution stops here.
+ */
 function invalidCall() {
   header("Content-Type: text/plain; charset=UTF-8");
   print(_("Invalid call!"));
   die();
 }
 
-/** Handle errors with an XML message. */
+/**
+ * Handle errors with an XML message. Execution stops here.
+ *
+ * @param string $errormsg error message
+ */
 function errorAsXml($errormsg) {
   header("Content-Type: text/xml; charset=UTF-8");
   $GLOBALS['smarty']->assign("errormsg", $errormsg);
@@ -80,7 +86,11 @@ function errorAsXml($errormsg) {
   die();
 }
 
-/** Handle errors with an HTML error page. */
+/**
+ * Handle errors with an HTML error page. Execution stops here.
+ *
+ * @param string $errormsg error msg
+ */
 function errorAsHtml($errormsg) {
   header("Content-Type: text/html; charset=UTF-8");
   $GLOBALS['smarty']->assign("errormsg", $errormsg);
@@ -88,6 +98,13 @@ function errorAsHtml($errormsg) {
   die();
 }
 
+/**
+ * Get the full path of relative directory name.
+ *
+ * @param string $dirname directory name relative to configured
+ * $davconfig['dav.dir']
+ * @return string fully qualified directory name
+ */
 function getFullPath($dirname) {
   return $GLOBALS['davconfig']['dav.dir'] . DIRECTORY_SEPARATOR . $dirname;
 }
@@ -139,7 +156,14 @@ if (!empty($errmsgs)) {
   errorAsHtml(implode("<br />", $errmsgs));
 }
 
-function cmp_by_usernames($user1, $user2) {
+/**
+ * Compares two associative arrays of userdata by their username value.
+ *
+ * @param array &$user1 user data one
+ * @param array &$user2 user data two
+ * @return value of strcmp of the username values
+ */
+function cmp_by_usernames(&$user1, &$user2) {
   return strcmp($user1['username'], $user2['username']);
 }
 
diff --git a/admin/directories.php b/admin/directories.php
index c4c8121..dc5146a 100644
--- a/admin/directories.php
+++ b/admin/directories.php
@@ -50,7 +50,7 @@ $mandatorygroups = array(ADMIN_GROUP);
  * .htaccess file. Mandatory groups are excluded.
  *
  * @param string $dirname a fully qualified directory name
- * @return an array of group names
+ * @return array an array of group names
  */
 function getDirGroupsFromHtaccess($dirname) {
   $htaccessname = getFullPath($dirname) . DIRECTORY_SEPARATOR . ".htaccess";
@@ -79,9 +79,9 @@ function getDirGroupsFromHtaccess($dirname) {
  *
  * @param string $dirname a fully qualified directory name
  * @param array $retval a two component array index 0 is the file
- * count, index 2 is the accumulated size of files
- * @return array updated with the data from subdirectories and files
- * of $dirname
+ * count, index 1 is the accumulated size of files
+ * @return array array updated with the data from subdirectories and
+ * files of $dirname
  */
 function countFilesRecursive($dirname, $retval = array(0, 0)) {  
   $dh = opendir($dirname);
@@ -103,7 +103,7 @@ function countFilesRecursive($dirname, $retval = array(0, 0)) {
  * Gets the data of a directory.
  *
  * @param string $dirname a fully qualified directory name
- * @return array of containing directory data
+ * @return array array containing directory data
  */
 function getDirectoryData($dirname) {
   $dir = array();
@@ -119,7 +119,7 @@ function getDirectoryData($dirname) {
  * Gets XML encoded data of a directory.
  *
  * @param string $dirname dirname relative to {@link $davconfig['dav.dir']}
- * @return XML string
+ * @return string XML string
  */
 function getDirectoryDataAsXml($dirname) {
   if (is_dir(getFullPath($dirname))) {
@@ -134,8 +134,8 @@ function getDirectoryDataAsXml($dirname) {
 /**
  * Gets XML encoded data of a deleted directory.
  *
- * @param string $dirname directory name relative to {@link $davconfig['dav.dir']}
- * @return XML string
+ * @param string $dirname directory name relative to $davconfig['dav.dir']
+ * @return string XML string
  */
 function getDeletedDirectoryData($dirname) {
   header("Content-Type: text/xml; charset=UTF-8");
@@ -146,7 +146,7 @@ function getDeletedDirectoryData($dirname) {
  * Gets the list of directory data for all valid directories below
  * {@link $davconfig['dav.dir']}.
  *
- * @return array of directory data arrays
+ * @return array array of directory data arrays
  * @see #getDirectoryData(string)
  */
 function getDirectories() {