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() {