[prev in list] [next in list] [prev in thread] [next in thread]
List: wine-patches
Subject: [AppDb] [try2] improve comments
From: Jonathan Ernst <jonathan () ernstfamily ! ch>
Date: 2006-06-30 11:21:04
Message-ID: 1151666464.7953.20.camel () localhost
[Download RAW message or body]
[Attachment #2 (multipart/signed)]
[Attachment #4 (multipart/mixed)]
Apply this patch after the prefix patch.
Changelog:
- update the comments in some files
["comments.patch" (comments.patch)]
--- account.php 2006-06-30 08:31:33.000000000 +0200
+++ account.php 2006-06-30 13:14:58.000000000 +0200
@@ -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");
@@ -59,7 +68,7 @@ function do_account($cmd = null)
redirect(apidb_fullurl("index.php"));
exit;
}
- //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"); exit;
}
@@ -115,7 +124,7 @@ function cmd_do_new()
if($result == SUCCESS)
{
- /* if we can log the user in, log them in automatically */
+ // if we can log the user in, log them in automatically
if($user->login($aClean['ext_email'], $aClean['ext_password']) == SUCCESS)
$_SESSION['current'] = $user;
--- addcomment.php 2006-06-30 08:38:17.000000000 +0200
+++ addcomment.php 2006-06-30 13:09:33.000000000 +0200
@@ -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[
$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())
{
@@ -37,20 +43,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");
--- appimage.php 2006-06-30 08:31:33.000000000 +0200
+++ appimage.php 2006-06-30 09:34:02.000000000 +0200
@@ -1,11 +1,26 @@
<?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
+ * - add require(BASE."include/filter.php"); and get rid of $aClean handling in \
this file + * - use // for single line comments
+ */
+// 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 +28,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.");
--- appview.php 2006-06-30 09:27:05.000000000 +0200
+++ appview.php 2006-06-30 13:15:40.000000000 +0200
@@ -1,11 +1,23 @@
<?php
-/**********************************/
-/* code to display an application */
-/**********************************/
-
-/*
- * application environment
+/**
+ * Displays an application or a version.
+ *
+ * Mandatory parameters:
+ * - iAppId, application identifier
+ * XOR
+ * - 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,
/**
- * display the SUB apps that belong to this app
+ * Displays the SUB apps that belong to this application.
*/
function display_bundle($iAppId)
{
--- deletecomment.php 2006-06-30 08:31:33.000000000 +0200
+++ deletecomment.php 2006-06-30 09:34:17.000000000 +0200
@@ -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($_REQUES
$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))
@@ -29,12 +36,13 @@ if (!$_SESSION['current']->hasPriv("admi
exit;
}
+// 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";
@@ -51,6 +59,7 @@ if($_SESSION['current']->getPref("confir
echo "</form>";
apidb_footer();
+// otherwise, just delete the comment
} else
{
$oComment->delete($aClean['sWhy']);
--- index.php 2006-06-30 08:32:01.000000000 +0200
+++ index.php 2006-06-30 13:10:24.000000000 +0200
@@ -1,11 +1,13 @@
<?php
-/***********************************/
-/* application database index page */
-/***********************************/
-
-/*
- * application environment
- */
+/**
+ * Application database index page.
+ *
+ * TODO:
+ * - rename outputTopXRowAppsFromRating according to our coding standards
+ * - rename variables that don't follow our coding standards
+ */
+
+// 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 cont
$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";
--- preferences.php 2006-06-30 08:32:01.000000000 +0200
+++ preferences.php 2006-06-30 13:14:39.000000000 +0200
@@ -1,13 +1,32 @@
<?php
-/*******************************/
-/* preferences and user editor */
-/*******************************/
-
-/*
- * application environment
- */
+/**
+ * User's role and preferences editor.
+ *
+ * Optional parameters:
+ * - iUserId, user identifier (when an administrator edits another user)
+ * - iLimit
+ * - sOrderBy
+ * - sExtPassword, new password
+ * - sExtPassword2, new password confirmation
+ * - sExtEmail, e-mail address
+ * - sExtRealname, user's real name
+ * - sCVSrelease, user's Wine release
+ * - sExtHasadmin, "on" if user is an administrator
+ *
+ * TODO:
+ * - document iLimit and sOrderBy
+ * - replace sOrderBy with iOrderBy and use constats for each accepted value
+ * - replace sExt[.*] with s[.*]
+ * - replace sCVSrelease with sWineRelease or (better)
+ * with iWineRelease that would reference Wine release in bugzilla database
+ * (this would require changing user->sWineRelease too)
+ * - add a field to prefs_list to flag the user level for the pref
+ * - move and rename functions in their respective modules
+ */
+
+// application environment
include("path.php");
-include(BASE."include/"."incl.php");
+include(BASE."include/incl.php");
$aClean = array(); //array of filtered user input
@@ -57,8 +76,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")
@@ -111,7 +129,7 @@ if($_POST)
$oUser->setPref($arr[1], $value);
}
- /* make sure the user enters the same password twice */
+ // make sure the user enters the same password twice
if ($aClean['sExtPassword'] == $aClean['sExtPassword2'])
{
$str_passwd = $aClean['sExtPassword'];
@@ -121,12 +139,12 @@ if($_POST)
addmsg("The Passwords you entered did not match.", "red");
}
- /* update user data fields */
+ // update user data fields
$oUser->sEmail = $aClean['sExtEmail'];
$oUser->sRealname = $aClean['sExtRealname'];
$oUser->sWineRelease = $aClean['sCVSrelease'];
- /* if the password was empty in both cases then skip updating the users password \
*/ + // if the password was empty in both cases then skip updating the users \
password if($str_passwd != "")
{
if(!$oUser->update_password($str_passwd))
--- screenshots.php 2006-06-30 08:32:01.000000000 +0200
+++ screenshots.php 2006-06-30 13:15:25.000000000 +0200
@@ -1,13 +1,24 @@
<?php
-/*******************************************************************/
-/* this script expects appId and optionally versionId as arguments */
-/* OR */
-/* cmd and imageId */
-/*******************************************************************/
-
-/*
- * application environment
- */
+/**
+ * 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
include("path.php");
require(BASE."include/incl.php");
require_once(BASE."include/screenshot.php");
@@ -22,9 +33,7 @@ $aClean['sScreenshotDesc'] = makeSafe($_
$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 2006-06-30 08:32:01.000000000 +0200
+++ search.php 2006-06-30 13:15:52.000000000 +0200
@@ -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 2006-06-30 08:32:01.000000000 +0200
+++ viewbugs.php 2006-06-30 13:09:58.000000000 +0200
@@ -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");
@@ -57,8 +64,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> </td>',"\n";
echo '</tr>',"\n";
["signature.asc" (application/pgp-signature)]
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic