From a34058b9241b2a9852eff71bc1fc39482fcf79f0 Mon Sep 17 00:00:00 2001
From: Jonathan Ernst <jonathan@ernstfamily.ch>
Date: Thu, 6 Jul 2006 18:37:34 +0000
Subject: [PATCH] Update the comments in some files

---
 account.php          | 17 +++++++++++++----
 addcomment.php       | 32 ++++++++++++++++----------------
 appbrowse.php        | 10 +++++++---
 appimage.php         | 28 ++++++++++++++++++++--------
 appview.php          | 26 +++++++++++++++++++-------
 deletecomment.php    | 29 +++++++++++++++++++----------
 index.php            | 16 +++++++++-------
 maintainerdelete.php | 24 ++++++++++++++++++------
 maintainersubmit.php | 22 ++++++++++++++++------
 preferences.php      | 33 ++++++++++++++++++++++++---------
 screenshots.php      | 38 +++++++++++++++++++++++---------------
 search.php           | 16 ++++++++++------
 viewbugs.php         | 16 +++++++++++-----
 13 files changed, 205 insertions(+), 102 deletions(-)

diff --git a/account.php b/account.php
index bdde0d6..4049d8a 100644
--- a/account.php
+++ b/account.php
@@ -1,7 +1,16 @@
 <?php
-/********************************************/
-/* Account Login / Logout Handler for AppDB */
-/********************************************/
+/**
+ * Account login/logout handler.
+ *
+ * Mandatory parameters:
+ *  - sCmd, action to perform ("new", "do_new", "login", "do_login", "send_passwd", "logout")
+ * 
+ * TODO:
+ *  - replace sCmd with iAction and replace "new", "login", etc. with integer constants NEW, LOGIN, etc.
+ *  - move functions into their respective modules (probably static methods of user class)
+ */
+
+// application environment
 include("path.php");
 require(BASE."include/incl.php");
 require(BASE."include/mail.php");
@@ -60,7 +69,7 @@ function do_account($sCmd = null)
 
             redirect(apidb_fullurl("index.php"));
     }
-    //not valid command, display error page
+    // not valid command, display error page
     util_show_error_page("Internal Error","This module was called with incorrect parameters");
 }
 
diff --git a/addcomment.php b/addcomment.php
index b156350..df15476 100644
--- a/addcomment.php
+++ b/addcomment.php
@@ -1,4 +1,17 @@
 <?php
+/**
+ * Adds a new comment.
+ *
+ * Mandatory parameters:
+ *  - iVersionId, version identifier
+ *
+ * Optional parameters:
+ *  - iThread, parent comment identifier 
+ *  - sBody, body of the comment
+ *  - sSubject, title of the comment
+ */
+
+// application environment
 include("path.php");
 require(BASE."include/incl.php");
 require(BASE."include/application.php");
@@ -11,13 +24,6 @@ $aClean['iThread'] = makeSafe($_REQUEST['iThread']);
 $aClean['sBody'] = makeSafe($_REQUEST['sBody']);
 $aClean['sSubject'] = makeSafe($_REQUEST['sSubject']);
 
-/********************************/
-/* code to submit a new comment */
-/********************************/
-    
-/*
- * application environment
- */
 // you must be logged in to submit comments
 if(!$_SESSION['current']->isLoggedIn())
 {
@@ -34,20 +40,14 @@ if(!is_numeric($aClean['iThread']))
   $aClean['iThread'] = 0;
 }
 
-############################
-# ADDS COMMENT TO DATABASE #
-############################
+// the user submitted his comment
 if(!empty($aClean['sBody']))
 {
     $oComment = new Comment();
     $oComment->create($aClean['sSubject'], $aClean['sBody'], $aClean['iThread'], $aClean['iVersionId']);
     redirect(apidb_fullurl("appview.php?iVersionId=".$oComment->iVersionId));
-}
-
-################################
-# USER WANTS TO SUBMIT COMMENT #
-################################
-else
+// let's show the comment form
+} else
 {
   apidb_header("Add Comment");
 
diff --git a/appbrowse.php b/appbrowse.php
index 80ba674..5df818d 100644
--- a/appbrowse.php
+++ b/appbrowse.php
@@ -1,8 +1,12 @@
 <?php
-/**********************************/
-/* code to BROWSE categories/apps */
-/**********************************/
+/**
+ * Application browser.
+ *
+ * Optional parameters:
+ *  - iCatId, shows applications that belong to the category identified by iCatId
+ */
 
+// application environment
 include("path.php");
 require(BASE."include/"."incl.php");
 require(BASE."include/"."appdb.php");
diff --git a/appimage.php b/appimage.php
index 69b387f..5dd4192 100644
--- a/appimage.php
+++ b/appimage.php
@@ -1,11 +1,24 @@
 <?php
-/*************************/
-/* code to show an image */
-/*************************/
+/**
+ * Shows a thumbnail or a full size screenshot.
+ *
+ * Mandatory parameters:
+ *  - iId, image identifier
+ * 
+ * Optional parameters:
+ *  - bThumbnail, "true" if we want to see a thumbnail, "false" otherwise
+ *  - sREQUEST_METHOD
+ * 
+ * TODO:
+ *  - rename and document sREQUEST_METHOD
+ *  - replace iId with iScreenshotId
+ *  - replace require_once with require after checking that it doesn't break anything
+ */
 
+// application environment
 include("path.php");
-require(BASE."include/"."incl.php");
-require_once(BASE."include/"."screenshot.php");
+require(BASE."include/incl.php");
+require_once(BASE."include/screenshot.php");
 
 $aClean = array(); //array of filtered user input
 
@@ -13,12 +26,11 @@ $aClean['iId'] = makeSafe($_REQUEST['iId']);
 $aClean['sREQUEST_METHOD'] = makeSafe($_REQUEST['sREQUEST_METHOD']);
 $aClean['bThumbnail'] = makeSafe($_REQUEST['bThumbnail']);
 
-/* an image doesn't have a link, so a cookie makes no sense */
+// an image doesn't have a link, so a cookie makes no sense
 header("Set-Cookie: ");
 header("Pragma: ");
 
-/* if the user isn't supposed to be viewing this image */
-/* display an error message and exit */
+// is the user supposed to be viewing this image ?
 if(!$_SESSION['current']->canViewImage($aClean['iId']))
     util_show_error_page("Insufficient privileges.");
 
diff --git a/appview.php b/appview.php
index af0b67a..7d06e43 100644
--- a/appview.php
+++ b/appview.php
@@ -1,11 +1,23 @@
 <?php
-/**********************************/
-/* code to display an application */
-/**********************************/
-
-/*
- * application environment
+/**
+ * Displays an application or a version.
+ *
+ * Mandatory parameters:
+ *  - iAppId, application identifier
+ *               OR
+ *  - iVersionId, version identifier
+ *
+ * Optional parameters:
+ *  - sSub, action to perform ("delete", "unqueue", "Submit a new bug link.", "StartMonitoring", "StopMonitoring")
+ *  - iBuglinkId, bug identifier to link a bug with a version
+ *
+ * TODO:
+ *  - replace sSub with iAction and replace "delete", "unqueue", etc. with integer constants DELETE, UNQUEUE, etc.
+ *  - move and rename display_catpath and display_bundle in their respective modules
+ *  - replace require_once with require after checking that it won't break anything
  */
+
+// application environment
 include("path.php");
 require(BASE."include/incl.php");
 require(BASE."include/application.php");
@@ -42,7 +54,7 @@ function display_catpath($catId, $appId, $versionId = '')
 
 
 /**
- * display the SUB apps that belong to this app 
+ * Displays the SUB apps that belong to this application.
  */
 function display_bundle($iAppId)
 {
diff --git a/deletecomment.php b/deletecomment.php
index 515c786..f13d212 100644
--- a/deletecomment.php
+++ b/deletecomment.php
@@ -1,11 +1,16 @@
 <?php
-/*******************/
-/* delete comments */
-/*******************/
-
-/*
- * application environment
+/**
+ * Deletes a comment.
+ *
+ * Mandatory parameters:
+ *  - iCommentId, comment identifier
+ *
+ * Optional parameters:
+ *  - sWhy, reason for deleting the comment
+ *  - iDeleteIt, 1 if the deletion has been confirmed
  */
+
+// application environment
 include("path.php");
 require(BASE."include/incl.php");
 require(BASE."include/application.php");
@@ -19,8 +24,10 @@ $aClean['iDeleteIt'] = makeSafe($_REQUEST['iDeleteIt']);
 
 $oComment = new Comment($aClean['iCommentId']);
 
-/* if we aren't an admin or the maintainer of this app we shouldn't be */
-/* allowed to delete any comments */
+/**
+ * if we aren't an admin or the maintainer of this app we shouldn't be 
+ * allowed to delete any comments
+ */
 if (!$_SESSION['current']->hasPriv("admin") 
  && !$_SESSION['current']->isMaintainer($oComment->iVersionId)
  && !$_SESSION['current']->isSuperMaintainer($oComment->iAppId))
@@ -28,12 +35,13 @@ if (!$_SESSION['current']->hasPriv("admin")
     util_show_error_page("You don't have sufficient privileges to delete this comment.");
 }
 
+// let's show the deletion form if the user want's to explain why he deleted the comment
 if($_SESSION['current']->getPref("confirm_comment_deletion") != "no" && !isset($aClean['iDeleteIt']))
 {
     apidb_header("Delete Comment");
-    $mesTitle = "<b>Please state why you are deleting the following comment</b>";
+    $sMessageTitle = "<b>Please state why you are deleting the following comment</b>";
     echo "<form method=\"post\" action=\"".$_SERVER['PHP_SELF']."\">\n";
-    echo html_frame_start($mesTitle,500,"",0);
+    echo html_frame_start($sMessageTitle,500,"",0);
     echo "<br />";
     echo html_frame_start($oComment->sSubject,500);
     echo htmlify_urls($oComment->sBody), "<br /><br />\n";
@@ -50,6 +58,7 @@ if($_SESSION['current']->getPref("confirm_comment_deletion") != "no" && !isset($
     echo "</form>";
 
     apidb_footer();
+// otherwise, just delete the comment
 } else
 {
     $oComment->delete($aClean['sWhy']);
diff --git a/index.php b/index.php
index e9605c5..fe8cb30 100644
--- a/index.php
+++ b/index.php
@@ -1,11 +1,13 @@
 <?php
-/***********************************/
-/* application database index page */
-/***********************************/
+/**
+ * Application database index page.
+ *
+ * TODO:
+ *  - rename outputTopXRowAppsFromRating according to our coding standards
+ *  - rename variables that don't follow our coding standards
+ */
 
-/*
- * application environment
- */ 
+// application environment
 include("path.php");
 require(BASE."include/incl.php");
 require(BASE."include/application.php");
@@ -69,7 +71,7 @@ If you have screenshots or links to contribute, please browse the database and u
     $voteAppId = $oRow->appId;
     $voteAppName = $oRow->appName;
 
-    /* don't mention the top application if there are no votes yet */
+    // don't mention the top application if there are no votes yet
     if($voteAppId != "")
     {
        echo "There are <b>$numApps</b> applications currently in the database with\n";
diff --git a/maintainerdelete.php b/maintainerdelete.php
index 5541f01..8d24131 100644
--- a/maintainerdelete.php
+++ b/maintainerdelete.php
@@ -1,11 +1,23 @@
 <?php
-/*******************************/
-/* code to delete a maintainer */
-/*******************************/
+/**
+ * Deletes a maintainer.
+ *
+ * Mandatory parameters:
+ *  - iAppId, application identifier
+ *            AND/OR
+ *  - iVersionId, version identifier
+ * 
+ * Optional parameters:
+ *  - iSuperMaintainer, 1 if we want to delete a supermaintainer instead of a normal maintainer
+ *  - iConfirmed, 1 if the deletion is confirmed
+ * 
+ * TODO:
+ *  - replace iSuperMaintainer with bIsSuperMaintainer
+ *  - replace iConfirmed with bHasConfirmed
+ *  - $oApp is not defined in the else part of this script
+ */
 
-/*
- * application environment
- */ 
+// application environment
 include("path.php");
 require(BASE."include/incl.php");
 require(BASE."include/category.php");
diff --git a/maintainersubmit.php b/maintainersubmit.php
index 6d1fdab..fb7c58e 100644
--- a/maintainersubmit.php
+++ b/maintainersubmit.php
@@ -1,11 +1,21 @@
 <?php
-/*******************************/
-/* code to submit a maintainer */
-/*******************************/
+/**
+ * Adds a maintainer.
+ *
+ * Mandatory parameters:
+ *  - iAppId, application identifier
+ *            AND/OR
+ *  - iVersionId, version identifier
+ * 
+ * Optional parameters:
+ *  - iSuperMaintainer, 1 if we want to delete a supermaintainer instead of a normal maintainer
+ *  - sMaintainReason, why the users want to be a maintainer
+ * 
+ * TODO:
+ *  - replace iSuperMaintainer with bIsSuperMaintainer
+ */
 
-/*
- * application environment
- */ 
+// application environment
 include("path.php");
 require(BASE."include/incl.php");
 require(BASE."include/category.php");
diff --git a/preferences.php b/preferences.php
index 5b5110f..1a8c08e 100644
--- a/preferences.php
+++ b/preferences.php
@@ -1,13 +1,29 @@
 <?php
-/*******************************/
-/* preferences and user editor */
-/*******************************/
+/**
+ * User's role and preferences editor.
+ *
+ * Optional parameters:
+ *  - iUserId, user identifier (when an administrator edits another user)
+ *  - iLimit
+ *  - sOrderBy
+ *  - sUserPassword, new password
+ *  - sUserPassword2, new password confirmation
+ *  - sUserEmail, e-mail address
+ *  - sUserRealname, user's real name
+ *  - sWineRelease, user's Wine release
+ *  - sHasAdmin, "on" if user is an administrator
+ * 
+ * TODO:
+ *  - rename sHasAdmin with bIsAdmin
+ *  - document iLimit and sOrderBy
+ *  - replace sOrderBy with iOrderBy and use constants for each accepted value
+ *  - add a field to prefs_list to flag the user level for the pref
+ *  - move and rename functions in their respective modules
+ */
 
-/*
- * application environment
- */     
+// application environment
 include("path.php");
-include(BASE."include/"."incl.php");
+include(BASE."include/incl.php");
 
 $aClean = array(); //array of filtered user input
 
@@ -54,8 +70,7 @@ function build_prefs_list()
     $hResult = query_parameters("SELECT * FROM prefs_list ORDER BY id");
     while($hResult && $r = mysql_fetch_object($hResult))
     {
-            //skip admin options
-            //TODO: add a field to prefs_list to flag the user level for the pref
+            // skip admin options
             if(!$_SESSION['current']->hasPriv("admin"))
             {
                     if($r->name == "query:mode")
diff --git a/screenshots.php b/screenshots.php
index cce7f7d..27d182c 100644
--- a/screenshots.php
+++ b/screenshots.php
@@ -1,13 +1,24 @@
 <?php
-/*******************************************************************/
-/* this script expects appId and optionally versionId as arguments */
-/* OR                                                              */
-/* cmd and imageId                                                 */
-/*******************************************************************/
+/**
+ * Shows a page with several screenshot thumbnails.
+ *
+ * Mandatory parameters:
+ *  - iAppId, application identifier
+ *            AND/OR
+ *  - iVersionId, version identifier
+ * 
+ * Optional parameters:
+ *  - iImageId, image identifier (for deletion)
+ *  - sScreenshotDesc, screenshot description (for insertion)
+ *  - sCmd, action to perform ("screenshot_upload", "delete")
+ * 
+ * TODO:
+ *  - replace iImageId with iScreenshotId
+ *  - replace sCmd with iAction and replace "delete", "screenshot_upload", etc. with integer constants DELETE, UPLOAD, etc.
+ *  - replace require_once with require after checking that it won't break anything
+ */
 
-/*
- * application environment
- */ 
+// application environment
 include("path.php");
 require(BASE."include/incl.php");
 require_once(BASE."include/screenshot.php");
@@ -22,9 +33,7 @@ $aClean['sScreenshotDesc'] = makeSafe($_REQUEST['sScreenshotDesc']);
 $aClean['iImageId'] = makeSafe($_REQUEST['iImageId']);
 $aClean['iAppId'] = makeSafe($_REQUEST['iAppId']);
 
-/*
- * We issued a command.
- */ 
+// we issued a command
 if($aClean['sCmd'])
 {
     // process screenshot upload
@@ -49,9 +58,7 @@ if($aClean['sCmd'])
 }
 
 
-/*
- * We didn't issued any command.
- */ 
+// we didn't issued any command
 $hResult = get_screenshots($aClean['iAppId'], $aClean['iVersionId']);   
 apidb_header("Screenshots");
 $oApp = new Application($aClean['iAppId']);
@@ -106,9 +113,9 @@ if($hResult && mysql_num_rows($hResult))
  echo "<br />Please consider submitting a screenshot for the selected version yourself.</p>";
 }
 
+// let's show the screenshot uploading box
 if($aClean['iVersionId'])
 {
-    //image upload box
     echo '<form enctype="multipart/form-data" action="screenshots.php" name="sImageForm" method="post">',"\n";
     echo html_frame_start("Upload Screenshot","400","",0);
     echo '<table border=0 cellpadding=6 cellspacing=0 width="100%">',"\n";
@@ -124,5 +131,6 @@ if($aClean['iVersionId'])
     echo '<input type="hidden" name="iVersionId" value="'.$aClean['iVersionId'].'"></form />',"\n";
 }
 echo html_back_link(1);
+
 apidb_footer();
 ?>
diff --git a/search.php b/search.php
index 6240a4d..224cbeb 100644
--- a/search.php
+++ b/search.php
@@ -1,11 +1,15 @@
 <?php
-/*****************/
-/* search engine */
-/*****************/
+/**
+ * Search engine.
+ *
+ * Mandatory parameters:
+ *  - sSearchQuery, user search query
+ * 
+ * TODO:
+ *  - prefix perform_search_and_output_results with a module prefix
+ */
 
-/*
- * application environment
- */ 
+// application environment
 include("path.php");
 require(BASE."include/incl.php");
 require(BASE."include/application.php");
diff --git a/viewbugs.php b/viewbugs.php
index 25ee5b0..7657266 100644
--- a/viewbugs.php
+++ b/viewbugs.php
@@ -1,8 +1,15 @@
 <?php
-/************************************************/
-/* Show all applications that have a bug link # */
-/************************************************/
+/**
+ * Shows all versions that have the same bug link.
+ *
+ * Mandatory parameters:
+ *  - iBugId, bug identifier
+ * 
+ * TODO:
+ *  - replace the check is_numeric($aClean['iBugId']) with an is_empty check when filtering is in place
+ */
 
+// application environment
 include("path.php");
 require(BASE."include/incl.php");
 
@@ -54,8 +61,7 @@ if(!is_numeric($aClean['iBugId']))
         }
     }
 
-    /* allow users to search for other apps */
-
+    // allow users to search for other apps
     echo '<tr class=color2>',"\n";
     echo '    <td align=center colspan=5>&nbsp</td>',"\n";
     echo '</tr>',"\n";