Update some comments

app/Http/Controllers/Api/AssetFilesController.php

@@ -29,11 +29,13 @@ use Route;
 
 
 /**
- * This class controls all actions related to assets for
+ * This class controls file related actions related
- * the Snipe-IT Asset Management application.
+ * to assets for the Snipe-IT Asset Management application.
+ *
+ * Based on the Assets/AssetFilesController by A. Gianotto <snipe@snipe.net>
  *
  * @version    v1.0
- * @author [A. Gianotto] [<snipe@snipe.net>]
+ * @author [T. Scarsbrook] [<snipe@scarzybrook.co.uk>]
  */
 class AssetFilesController extends Controller
 {
@@ -49,26 +51,32 @@ class AssetFilesController extends Controller
      */
     public function store(UploadFileRequest $request, $assetId = null)
     {
+        // Start by checking if the asset being acted upon exists
         if (! $asset = Asset::find($assetId)) {
             return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/hardware/message.does_not_exist')), 500);
         }
 
+        // Make sure we are allowed to update this asset
         $this->authorize('update', $asset);
 
-        if ($request->hasFile('file')) {
+	if ($request->hasFile('file')) {
+            // If the file storage directory doesn't exist; create it
             if (! Storage::exists('private_uploads/assets')) {
                 Storage::makeDirectory('private_uploads/assets', 775);
             }
 
+            // Loop over the attached files and add them to the asset
             foreach ($request->file('file') as $file) {
                 $file_name = $request->handleFile('private_uploads/assets/','hardware-'.$asset->id, $file);
                 
                 $asset->logUpload($file_name, e($request->get('notes')));
             }
 
+            // All done - report success
             return response()->json(Helper::formatStandardApiResponse('success', $asset, trans('admin/hardware/message.upload.success')));
         }
 
+        // We only reach here if no files were included in the POST, so tell the user this
         return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/hardware/message.upload.nofiles')), 500);
     }
 
@@ -83,6 +91,7 @@ class AssetFilesController extends Controller
      */
     public function list($assetId = null)
     {
+        // Start by checking if the asset being acted upon exists
         if (! $asset = Asset::find($assetId)) {
             return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/hardware/message.does_not_exist')), 500);
         }
@@ -91,18 +100,21 @@ class AssetFilesController extends Controller
         if (isset($asset->id)) {
             $this->authorize('view', $asset);
 
+            // Check that there are some uploads on this asset that can be listed
             if ($asset->uploads->count() > 0) {
                 $files = array();
                 foreach ($asset->uploads as $upload) {
                     array_push($files, $upload);
-                }
+		}
+                // Give the list of files back to the user
                 return response()->json(Helper::formatStandardApiResponse('success', $files, trans('admin/hardware/message.upload.success')));
             }
-            
+
+	    // There are no files. This possibly isn't the best response for this, but it does get the point across
             return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/hardware/message.download.no_match', ['id' => $fileId])), 500);
         }
 
-        // Send back an error message
+        // 
         return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/hardware/message.download.error', ['id' => $fileId])), 500);
     }
 
@@ -118,6 +130,7 @@ class AssetFilesController extends Controller
      */
     public function show($assetId = null, $fileId = null)
     {
+        // Start by checking if the asset being acted upon exists
         if (! $asset = Asset::find($assetId)) {
             return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/hardware/message.does_not_exist')), 500);
         }
@@ -126,10 +139,12 @@ class AssetFilesController extends Controller
         if (isset($asset->id)) {
             $this->authorize('view', $asset);
 
+            // Check that the file being requested exists for the asset
             if (! $log = Actionlog::whereNotNull('filename')->where('item_id', $asset->id)->find($fileId)) {
                 return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/hardware/message.download.no_match', ['id' => $fileId])), 500);
             }
 
+	    // Form the full filename with path
             $file = 'private_uploads/assets/'.$log->filename;
             \Log::debug('Checking for '.$file);
 
@@ -137,6 +152,7 @@ class AssetFilesController extends Controller
                 $file = 'private_uploads/audits/'.$log->filename;
             }
 
+            // Check the file actually exists on the filesystem
             if (! Storage::exists($file)) {
                 return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/hardware/message.download.does_not_exist', ['id' => $fileId])), 404);
             }
@@ -169,6 +185,7 @@ class AssetFilesController extends Controller
      */
     public function destroy($assetId = null, $fileId = null)
     {
+        // Start by checking if the asset being acted upon exists
         if (! $asset = Asset::find($assetId)) {
             return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/hardware/message.does_not_exist')), 500);
         }
@@ -178,16 +195,22 @@ class AssetFilesController extends Controller
         // the asset is valid
         if (isset($asset->id)) {
             $this->authorize('update', $asset);
+
+            // Check for the file
             $log = Actionlog::find($fileId);
-            if ($log) {
+	    if ($log) {
+                // Check the file actually exists, and delete it
                 if (Storage::exists($rel_path.'/'.$log->filename)) {
                     Storage::delete($rel_path.'/'.$log->filename);
-                }
+		}
+		// Delete the record of the file
                 $log->delete();
 
+                // All deleting done - notify the user of success
                 return response()->json(Helper::formatStandardApiResponse('success', null, trans('admin/hardware/message.deletefile.success')), 200);
             }
 
+            // The file doesn't seem to really exist, so report an error
             return response()->json(Helper::formatStandardApiResponse('error', null, trans('admin/hardware/message.deletefile.error')), 500);
         }