Update the comments in some files

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");
 }
 

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;
 }
 
-############################
+// the user submitted his comment
-# ADDS COMMENT TO DATABASE #
-############################
 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));
-}
+// let's show the comment form
-
+} else
-################################
-# USER WANTS TO SUBMIT COMMENT #
-################################
-else
 {
   apidb_header("Add Comment");
 

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");

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(BASE."include/incl.php");
-require_once(BASE."include/"."screenshot.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 */
+// is the user supposed to be viewing this image ?
-/* display an error message and exit */
 if(!$_SESSION['current']->canViewImage($aClean['iId']))
     util_show_error_page("Insufficient privileges.");
 

appview.php

@@ -1,11 +1,23 @@
 <?php
-/**********************************/
+/**
-/* code to display an application */
+ * Displays an application or a version.
-/**********************************/
+ *
-
+ * Mandatory parameters:
-/*
+ *  - iAppId, application identifier
- * application environment
+ *               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)
 {

deletecomment.php

@@ -1,11 +1,16 @@
 <?php
-/*******************/
+/**
-/* delete comments */
+ * Deletes a comment.
-/*******************/
+ *
-
+ * Mandatory parameters:
-/*
+ *  - iCommentId, comment identifier
- * application environment
+ *
+ * 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']);

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";

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");

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");

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
+            // skip admin options
-            //TODO: add a field to prefs_list to flag the user level for the pref
             if(!$_SESSION['current']->hasPriv("admin"))
             {
                     if($r->name == "query:mode")

screenshots.php

@@ -1,13 +1,24 @@
 <?php
-/*******************************************************************/
+/**
-/* this script expects appId and optionally versionId as arguments */
+ * Shows a page with several screenshot thumbnails.
-/* OR                                                              */
+ *
-/* cmd and imageId                                                 */
+ * 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();
 ?>

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");

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";