From 100dd6438eeb715ab86d7845d4034854ec1ad1a6 Mon Sep 17 00:00:00 2001
From: "green-ponies (jgen)" <jgen.tech@gmail.com>
Date: Sat, 3 Sep 2011 19:34:46 -0400
Subject: [PATCH] Added more comments and changed others for better doxygen
 support.

---
 ext/image/main.php  | 88 ++++++++++++++++++++++++++-------------------
 ext/upload/main.php | 21 +++++++----
 2 files changed, 65 insertions(+), 44 deletions(-)

diff --git a/ext/image/main.php b/ext/image/main.php
index ba3f1b9b..0dfeb775 100644
--- a/ext/image/main.php
+++ b/ext/image/main.php
@@ -1,21 +1,27 @@
 <?php
 /*
  * Name: Image Manager
- * Author: Shish
+ * Author: Shish <webmaster@shishnet.org>
+ * Modified by: jgen <jgen.tech@gmail.com>
  * Description: Handle the image database
  * Visibility: admin
  */
 
-/*
- * ImageAdditionEvent:
- *   $user  -- the user adding the image
- *   $image -- the image being added
- *
- * An image is being added to the database
+ /**
+ * An image is being added to the database.
  */
 class ImageAdditionEvent extends Event {
 	var $user, $image;
-
+	
+	/**
+	 * Inserts a new image into the database with its associated
+	 * information. Also calls TagSetEvent to set the tags for
+	 * this new image.
+	 *
+	 * @sa TagSetEvent
+	 * @param $user	The user adding the image
+	 * @param $image	The new image to add.
+	 */
 	public function ImageAdditionEvent(User $user, Image $image) {
 		$this->image = $image;
 		$this->user = $user;
@@ -30,34 +36,41 @@ class ImageAdditionException extends SCoreException {
 	}
 }
 
-/*
- * ImageDeletionEvent:
- *   $image -- the image being deleted
- *
- * An image is being deleted. Used by things like tags
- * and comments handlers to clean out related rows in
- * their tables
+/**
+ * An image is being deleted.
  */
 class ImageDeletionEvent extends Event {
 	var $image;
-
+	
+	/**
+	 * Deletes an image.
+	 * Used by things like tags and comments handlers to
+	 * clean out related rows in their tables.
+	 *
+	 * @param $image 	The image being deleted
+	*/
 	public function ImageDeletionEvent(Image $image) {
 		$this->image = $image;
 	}
 }
 
-/*
- * ImageReplaceEvent:
- *   $id     -- the ID of the image to replace
- *   $image  -- the image object of the new image to use
- *
- * This function replaces an image. Effectively it only
- * replaces the image file contents and leaves the tags
- * and such the same.
+/**
+ * An image is being replaced.
  */
 class ImageReplaceEvent extends Event {
 	var $id, $image;
-
+	
+	/**
+	 * Replaces an image.
+	 * Updates an existing ID in the database to use a new image
+	 * file, leaving the tags and such unchanged. Also removes 
+	 * the old image file and thumbnail from the disk.
+	 *
+	 * @param $id
+	 *   The ID of the image to replace
+	 * @param $image
+	 *   The image object of the new image to use
+	 */
 	public function ImageReplaceEvent($id, Image $image) {
 		$this->id = $id;
 		$this->image = $image;
@@ -72,15 +85,18 @@ class ImageReplaceException extends SCoreException {
 	}
 }
 
-
-/*
- * ThumbnailGenerationEvent:
- * Request a thumb be made for an image
+/**
+ * Request a thumbnail be made for an image object.
  */
 class ThumbnailGenerationEvent extends Event {
-	var $hash;
-	var $type;
-
+	var $hash, $type;
+	
+	/**
+	 * Request a thumbnail be made for an image object
+	 *
+	 * @param $hash	The unique hash of the image
+	 * @param $type	The type of the image
+	 */
 	public function ThumbnailGenerationEvent($hash, $type) {
 		$this->hash = $hash;
 		$this->type = $type;
@@ -95,8 +111,7 @@ class ThumbnailGenerationEvent extends Event {
  *   $image    -- the image who's link is being parsed
  */
 class ParseLinkTemplateEvent extends Event {
-	var $link, $original;
-	var $image;
+	var $link, $original, $image;
 
 	public function ParseLinkTemplateEvent($link, Image $image) {
 		$this->link = $link;
@@ -110,9 +125,8 @@ class ParseLinkTemplateEvent extends Event {
 }
 
 
-/*
- * A class to handle adding / getting / removing image
- * files from the disk
+/**
+ * A class to handle adding / getting / removing image files from the disk.
  */
 class ImageIO extends SimpleExtension {
 	public function onInitExt($event) {
diff --git a/ext/upload/main.php b/ext/upload/main.php
index 890e10f8..fd795fdf 100644
--- a/ext/upload/main.php
+++ b/ext/upload/main.php
@@ -5,17 +5,19 @@
  * Description: Allows people to upload files to the website
  */
 
-/*
- * DataUploadEvent:
- *   $user     -- the user uploading the data
- *   $tmpname  -- the temporary file used for upload
- *   $metadata -- info about the file, should contain at least "filename", "extension", "tags" and "source"
- *
- * Some data is being uploaded. Should be caught by a file handler.
+/**
+ * Occurs when some data is being uploaded.
  */
 class DataUploadEvent extends Event {
 	var $user, $tmpname, $metadata, $hash, $type, $image_id = -1;
 
+	/**
+	 * Some data is being uploaded.
+	 * This should be caught by a file handler.
+	 * @param $user The user uploading the data.
+	 * @param $tmpname The temporary file used for upload.
+	 * @param $metadata Info about the file, should contain at least "filename", "extension", "tags" and "source".
+	 */
 	public function DataUploadEvent(User $user, $tmpname, $metadata) {
 		assert(file_exists($tmpname));
 
@@ -34,6 +36,11 @@ class DataUploadEvent extends Event {
 
 class UploadException extends SCoreException {}
 
+/**
+ * Main upload class.
+ * All files that are uploaded to the site are handled through this class.
+ * This also includes transloaded files as well.
+ */
 class Upload implements Extension {
 	var $theme;
 // event handling {{{