From f6be78bdcfb0b20b750da8c014fa3a0e25ff3aaa Mon Sep 17 00:00:00 2001 From: Jan Dittberner 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("
", $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() {