Clean up packages.php and document new package functions

Signed-off-by: Callan Barrett <wizzomafizzo@gmail.com>
Signed-off-by: Loui Chang <louipc.ist@gmail.com>

2 files changed, 67 insertions, 29 deletions

diff --git a/web/html/packages.php b/web/html/packages.php
index a5718f3..ca2b26a 100644
--- a/web/html/packages.php
+++ b/web/html/packages.php
@@ -8,38 +8,31 @@ include("search_po.inc");   # use some form of this for i18n support
 set_lang();                 # this sets up the visitor's language
 check_sid();                # see if they're still logged in
 
-# set the title to something useful depending on
-# what "page" we're on
-#
+# Set the title to the current query if required
 if (isset($_GET['ID'])) {
-	$id = pkgname_from_id($_GET['ID']);
-	if (!empty($id)) {
-		$title = $id;
-	}
-}	else if (!empty($_GET['K'])) {
-	$title = "Search: " . $_GET['K'];
+	if ($pkgname = pkgname_from_id($_GET['ID'])) { $title = $pkgname; }
+} else if (!empty($_GET['K'])) {
+	$title = __("Search Criteria") . ": " . $_GET['K'];
 } else {
 	$title = __("Packages");
 }
 
-html_header($title);
-
-# get login privileges
-#
+# Retrieve account type
 if (isset($_COOKIE["AURSID"])) {
-	# Only logged in users can do stuff
-	#
 	$atype = account_from_sid($_COOKIE["AURSID"]);
 } else {
 	$atype = "";
 }
 
-# grab the list of Package IDs to be operated on
+# Grab the list of Package IDs to be operated on
 #
+# TODO: Convert this to a normal array of IDs to operate on and convert the
+# functions to use this format
 isset($_POST["IDs"]) ? $ids = $_POST["IDs"] : $ids = array();
 
-# determine what button the visitor clicked
-#
+html_header($title);
+
+# Determine what action to do
 if ($_POST['action'] == "do_Flag" || isset($_POST['do_Flag'])) {
 	print "<p>";
 	print pkg_flag($atype, $ids, True);
@@ -48,18 +41,14 @@ if ($_POST['action'] == "do_Flag" || isset($_POST['do_Flag'])) {
 	print "<p>";
 	print pkg_flag($atype, $ids, False);
 	print "</p>";
-} elseif ($_POST['action'] == "do_Disown" || isset($_POST['do_Disown'])) {
-	print "<p>";
-	print pkg_adopt($atype, $ids, False);
-	print "</p>";
-} elseif ($_POST['action'] == "do_Delete" || isset($_POST['do_Delete'])) {
-	print "<p>";
-	print pkg_delete($atype, $ids, False);
-	print "</p>";
 } elseif ($_POST['action'] == "do_Adopt" || isset($_POST['do_Adopt'])) {
 	print "<p>";
 	print pkg_adopt($atype, $ids, True);
 	print "</p>";
+} elseif ($_POST['action'] == "do_Disown" || isset($_POST['do_Disown'])) {
+	print "<p>";
+	print pkg_adopt($atype, $ids, False);
+	print "</p>";
 } elseif ($_POST['action'] == "do_Vote" || isset($_POST['do_Vote'])) {
 	print "<p>";
 	print pkg_vote($atype, $ids, True);
@@ -68,6 +57,10 @@ if ($_POST['action'] == "do_Flag" || isset($_POST['do_Flag'])) {
 	print "<p>";
 	print pkg_vote($atype, $ids, False);
 	print "</p>";
+} elseif ($_POST['action'] == "do_Delete" || isset($_POST['do_Delete'])) {
+	print "<p>";
+	print pkg_delete($atype, $ids);
+	print "</p>";
 } elseif ($_POST['action'] == "do_Notify" || isset($_POST['do_Notify'])) {
 	print "<p>";
 	print pkg_notify($atype, $ids);
@@ -86,10 +79,7 @@ if ($_POST['action'] == "do_Flag" || isset($_POST['do_Flag'])) {
 	}
 
 } else {
-	# just do a search
-	#
 	pkg_search_page($_COOKIE["AURSID"]);
-
 }
 
 html_footer(AUR_VERSION);
diff --git a/web/lib/pkgfuncs.inc b/web/lib/pkgfuncs.inc
index 4fbe666..9910379 100644
--- a/web/lib/pkgfuncs.inc
+++ b/web/lib/pkgfuncs.inc
@@ -984,6 +984,17 @@ function pkg_search_page($SID="") {
     return;
 }
 
+/**
+ * Flag and un-flag packages out-of-date
+ *
+ * @param string $atype Account type, output of account_from_sid
+ * @param array $ids Array of package IDs to flag/unflag, formatted as
+ * $package_id => $useless_crap
+ * @param boolean $action True flags out-of-date, false un-flags. Flags by
+ * default
+ *
+ * @return string Translated success or error messages
+ */
 function pkg_flag ($atype, $ids, $action = True) {
 	if (!$atype) {
 		if ($action) {
@@ -1058,6 +1069,15 @@ function pkg_flag ($atype, $ids, $action = True) {
 	}
 }
 
+/**
+ * Delete packages
+ *
+ * @param string $atype Account type, output of account_from_sid
+ * @param array $ids Array of package IDs to delete, formatted as
+ * $package_id => $useless_crap
+ *
+ * @return string Translated error or success message
+ */
 function pkg_delete ($atype, $ids) {
 	if (!$atype) {
 		return __("You must be logged in before you can disown packages.");
@@ -1131,6 +1151,16 @@ function pkg_delete ($atype, $ids) {
 	return __("The selected packages have been deleted.");
 }
 
+/**
+ * Adopt or disown packages
+ *
+ * @param string $atype Account type, output of account_from_sid
+ * @param array $ids Array of package IDs to adopt/disown, formatted as
+ * $package_id => $whatever
+ * @param boolean $action Adopts if true, disowns if false. Adopts by default
+ *
+ * @return string Translated error or success message
+ */
 function pkg_adopt ($atype, $ids, $action = True) {
 	if (!$atype) {
 		if ($action) {
@@ -1189,6 +1219,16 @@ function pkg_adopt ($atype, $ids, $action = True) {
 	}
 }
 
+/**
+ * Vote and un-vote for packages
+ *
+ * @param string $atype Account type, output of account_from_sid
+ * @param array $ids Array of package IDs to vote/un-vote, formatted as
+ * $package_id => $useless
+ * @param boolean $action Votes if true, un-votes if false. Votes by default
+ *
+ * @return string Translated error or success message
+ */
 function pkg_vote ($atype, $ids, $action = True) {
 	if (!$atype) {
 		if ($action) {
@@ -1266,6 +1306,14 @@ function pkg_vote ($atype, $ids, $action = True) {
 	}
 }
 
+/**
+ * Toggle notification of packages
+ *
+ * @param string $atype Account type, output of account_from_sid
+ * @param array $ids Array of package IDs to toggle, formatted as $package_id => $crap
+ *
+ * @return string Translated error or success message
+ */
 function pkg_notify ($atype, $ids, $action = True) {
 	if (!$atype) {
 #		return __("You must be logged in before you can get notifications on comments.");