Updated docblocks

app/Http/Controllers/AccessoriesController.php

@@ -524,33 +524,33 @@ class AccessoriesController extends Controller
         return Redirect::to("admin/accessories")->with('error', Lang::get('admin/accessories/message.checkin.error'));
     }
 
-  /**
+    /**
-  * Generates the JSON response for accessories listing view.
+    * Generates the JSON response for accessories listing view.
-  *
+    *
-  * Example:
+    * Example:
-  * {
+    * {
-  *  "actions": "(links to available actions)",
+    *  "actions": "(links to available actions)",
-  *  "category": "(link to category)",
+    *  "category": "(link to category)",
-  *  "companyName": "My Company",
+    *  "companyName": "My Company",
-  *  "location":  "My Location",
+    *  "location":  "My Location",
-  *  "min_amt": 2,
+    *  "min_amt": 2,
-  *  "name":  "(link to accessory),
+    *  "name":  "(link to accessory),
-  *  "numRemaining": 6,
+    *  "numRemaining": 6,
-  *  "order_number": null,
+    *  "order_number": null,
-  *  "purchase_cost": "0.00",
+    *  "purchase_cost": "0.00",
-  *  "purchase_date": null,
+    *  "purchase_date": null,
-  *  "qty": 7
+    *  "qty": 7
-  *  },
+    *  },
-  *
+    *
-  * The names of the fields in the returns JSON correspond directly to the the
+    * The names of the fields in the returns JSON correspond directly to the the
-  * names of the fields in the bootstrap-tables in the view.
+    * names of the fields in the bootstrap-tables in the view.
-  *
+    *
-  * For debugging, see at /api/accessories/list
+    * For debugging, see at /api/accessories/list
-  *
+    *
-  * @author [A. Gianotto] [<snipe@snipe.net>]
+    * @author [A. Gianotto] [<snipe@snipe.net>]
-  * @param  int  $accessoryId
+    * @param  int  $accessoryId
-  * @return string JSON containing accessories and their associated atrributes.
+    * @return string JSON containing accessories and their associated atrributes.
-  **/
+    **/
     public function getDatatable(Request $request)
     {
         $accessories = Accessory::select('accessories.*')->with('category', 'company')

app/Http/Controllers/CompaniesController.php

@@ -17,16 +17,38 @@ use View;
 
 final class CompaniesController extends Controller
 {
+
+    /**
+    * Returns view to display listing of companies.
+    *
+    * @author [Abdullah Alansari] [<ahimta@gmail.com>]
+    * @since [v1.8]
+    * @return View
+    */
     public function getIndex()
     {
         return View::make('companies/index')->with('companies', Company::all());
     }
 
+    /**
+    * Returns view to create a new company.
+    *
+    * @author [Abdullah Alansari] [<ahimta@gmail.com>]
+    * @since [v1.8]
+    * @return View
+    */
     public function getCreate()
     {
         return View::make('companies/edit')->with('company', new Company);
     }
 
+    /**
+    * Save data from new company form.
+    *
+    * @author [Abdullah Alansari] [<ahimta@gmail.com>]
+    * @since [v1.8]
+    * @return Redirect
+    */
     public function postCreate()
     {
         $company = new Company;
@@ -42,6 +64,15 @@ final class CompaniesController extends Controller
 
     }
 
+
+    /**
+    * Return form to edit existing company.
+    *
+    * @author [Abdullah Alansari] [<ahimta@gmail.com>]
+    * @since [v1.8]
+    * @param int $companyId
+    * @return View
+    */
     public function getEdit($companyId)
     {
         if (is_null($company = Company::find($companyId))) {
@@ -52,6 +83,14 @@ final class CompaniesController extends Controller
         }
     }
 
+    /**
+    * Save data from edit company form.
+    *
+    * @author [Abdullah Alansari] [<ahimta@gmail.com>]
+    * @since [v1.8]
+    * @param int $companyId
+    * @return Redirect
+    */
     public function postEdit($companyId)
     {
         if (is_null($company = Company::find($companyId))) {
@@ -72,6 +111,14 @@ final class CompaniesController extends Controller
         }
     }
 
+    /**
+    * Delete company
+    *
+    * @author [Abdullah Alansari] [<ahimta@gmail.com>]
+    * @since [v1.8]
+    * @param int $companyId
+    * @return Redirect
+    */
     public function postDelete($companyId)
     {
         if (is_null($company = Company::find($companyId))) {

app/Http/Controllers/ComponentsController.php

@@ -1,11 +1,11 @@
 <?php
 /**
- * This controller handles all actions related to Asset Models for
+ * This controller handles all actions related to Components for
  * the Snipe-IT Asset Management application.
  *
  * PHP version 5.5.9
  * @package    Snipe-IT
- * @version    v1.0
+ * @version    v3.0
  */
  namespace App\Http\Controllers;
 
@@ -31,11 +31,14 @@ use View;
 class ComponentsController extends Controller
 {
     /**
-     * Show a list of all the components.
+    * Returns a view that invokes the ajax tables which actually contains
-     *
+    * the content for the components listing, which is generated in getDatatable.
-     * @return View
+    *
-     */
+    * @author [A. Gianotto] [<snipe@snipe.net>]
-
+    * @see ComponentsController::getDatatable() method that generates the JSON response
+    * @since [v3.0]
+    * @return View
+    */
     public function getIndex()
     {
         return View::make('components/index');
@@ -43,10 +46,13 @@ class ComponentsController extends Controller
 
 
     /**
-     * Component create.
+    * Returns a form to create a new component.
-     *
+    *
-     * @return View
+    * @author [A. Gianotto] [<snipe@snipe.net>]
-     */
+    * @see ComponentsController::postCreate() method that stores the data
+    * @since [v3.0]
+    * @return View
+    */
     public function getCreate()
     {
         // Show the page
@@ -63,10 +69,13 @@ class ComponentsController extends Controller
 
 
     /**
-     * Component create form processing.
+    * Validate and store data for new component.
-     *
+    *
-     * @return Redirect
+    * @author [A. Gianotto] [<snipe@snipe.net>]
-     */
+    * @see ComponentsController::getCreate() method that generates the view
+    * @since [v3.0]
+    * @return Redirect
+    */
     public function postCreate()
     {
 
@@ -108,11 +117,14 @@ class ComponentsController extends Controller
     }
 
     /**
-     * Component update.
+    * Return a view to edit a component.
-     *
+    *
-     * @param  int  $componentId
+    * @author [A. Gianotto] [<snipe@snipe.net>]
-     * @return View
+    * @see ComponentsController::postEdit() method that stores the data.
-     */
+    * @since [v3.0]
+    * @param int $componentId
+    * @return View
+    */
     public function getEdit($componentId = null)
     {
         // Check if the component exists
@@ -135,11 +147,14 @@ class ComponentsController extends Controller
 
 
     /**
-     * Component update form processing page.
+    * Return a view to edit a component.
-     *
+    *
-     * @param  int  $componentId
+    * @author [A. Gianotto] [<snipe@snipe.net>]
-     * @return Redirect
+    * @see ComponentsController::getEdit() method presents the form.
-     */
+    * @param int $componentId
+    * @since [v3.0]
+    * @return Redirect
+    */
     public function postEdit($componentId = null)
     {
         // Check if the blog post exists
@@ -187,11 +202,13 @@ class ComponentsController extends Controller
     }
 
     /**
-     * Delete the given component.
+    * Delete a component.
-     *
+    *
-     * @param  int  $componentId
+    * @author [A. Gianotto] [<snipe@snipe.net>]
-     * @return Redirect
+    * @since [v3.0]
-     */
+    * @param int $componentId
+    * @return Redirect
+    */
     public function getDelete($componentId)
     {
         // Check if the blog post exists
@@ -220,17 +237,18 @@ class ComponentsController extends Controller
     }
 
 
-
-
     /**
-    *  Get the component information to present to the component view page
+    * Return a view to display component information.
     *
-    * @param  int  $componentId
+    * @author [A. Gianotto] [<snipe@snipe.net>]
+    * @see ComponentsController::getDataView() method that generates the JSON response
+    * @since [v3.0]
+    * @param int $componentId
     * @return View
-    **/
+    */
-    public function getView($componentID = null)
+    public function getView($componentId = null)
     {
-        $component = Component::find($componentID);
+        $component = Component::find($componentId);
 
         if (isset($component->id)) {
 
@@ -252,8 +270,14 @@ class ComponentsController extends Controller
     }
 
     /**
-    * Check out the component to a person
+    * Returns a view that allows the checkout of a component to an asset.
-    **/
+    *
+    * @author [A. Gianotto] [<snipe@snipe.net>]
+    * @see ComponentsController::postCheckout() method that stores the data.
+    * @since [v3.0]
+    * @param int $componentId
+    * @return View
+    */
     public function getCheckout($componentId)
     {
         // Check if the component exists
@@ -272,8 +296,14 @@ class ComponentsController extends Controller
     }
 
     /**
-    * Check out the component to a person
+    * Validate and store checkout data.
-    **/
+    *
+    * @author [A. Gianotto] [<snipe@snipe.net>]
+    * @see ComponentsController::getCheckout() method that returns the form.
+    * @since [v3.0]
+    * @param int $componentId
+    * @return Redirect
+    */
     public function postCheckout(ComponentCheckoutRequest $request, $componentId)
     {
       // Check if the component exists
@@ -354,6 +384,15 @@ class ComponentsController extends Controller
     }
 
 
+    /**
+    * Generates the JSON response for accessories listing view.
+    *
+    * For debugging, see at /api/accessories/list
+    *
+    * @author [A. Gianotto] [<snipe@snipe.net>]
+    * @since [v3.0]
+    * @return string JSON
+    **/
     public function getDatatable()
     {
         $components = Component::select('components.*')->whereNull('components.deleted_at')
@@ -426,12 +465,20 @@ class ComponentsController extends Controller
 
     }
 
-    public function getDataView($componentID)
+    /**
+    * Return JSON data to populate the components view,
+    *
+    * @author [A. Gianotto] [<snipe@snipe.net>]
+    * @see ComponentsController::getView() method that returns the view.
+    * @since [v3.0]
+    * @param int $componentId
+    * @return string JSON
+    */
+    public function getDataView($componentId)
     {
         //$component = Component::find($componentID);
-        $component = Component::with('assets')->find($componentID);
+        $component = Component::with('assets')->find($componentId);
 
-  //  $component->load('componentAssigments.admin','componentAssigments.user');
 
         if (!Company::isCurrentUserHasAccess($component)) {
             return ['total' => 0, 'rows' => []];

app/Http/Controllers/ConsumablesController.php

@@ -29,11 +29,13 @@ use View;
 class ConsumablesController extends Controller
 {
     /**
-     * Show a list of all the consumables.
+    * Return a view to display component information.
-     *
+    *
-     * @return View
+    * @author [A. Gianotto] [<snipe@snipe.net>]
-     */
+    * @see ConsumablesController::getDatatable() method that generates the JSON response
-
+    * @since [v1.0]
+    * @return View
+    */
     public function getIndex()
     {
         return View::make('consumables/index');
@@ -41,10 +43,13 @@ class ConsumablesController extends Controller
 
 
     /**
-     * Consumable create.
+    * Return a view to display the form view to create a new consumable
-     *
+    *
-     * @return View
+    * @author [A. Gianotto] [<snipe@snipe.net>]
-     */
+    * @see ConsumablesController::postCreate() method that stores the form data
+    * @since [v1.0]
+    * @return View
+    */
     public function getCreate()
     {
         // Show the page
@@ -61,17 +66,16 @@ class ConsumablesController extends Controller
 
 
     /**
-     * Consumable create form processing.
+    * Validate and store new consumable data.
-     *
+    *
-     * @return Redirect
+    * @author [A. Gianotto] [<snipe@snipe.net>]
-     */
+    * @see ConsumablesController::getCreate() method that returns the form view
+    * @since [v1.0]
+    * @return Redirect
+    */
     public function postCreate()
     {
-
-        // create a new model instance
         $consumable = new Consumable();
-
-        // Update the consumable data
         $consumable->name                   = e(Input::get('name'));
         $consumable->category_id            = e(Input::get('category_id'));
         $consumable->location_id            = e(Input::get('location_id'));
@@ -106,11 +110,14 @@ class ConsumablesController extends Controller
     }
 
     /**
-     * Consumable update.
+    * Returns a form view to edit a consumable.
-     *
+    *
-     * @param  int  $consumableId
+    * @author [A. Gianotto] [<snipe@snipe.net>]
-     * @return View
+    * @param  int $consumableId
-     */
+    * @see ConsumablesController::postEdit() method that stores the form data.
+    * @since [v1.0]
+    * @return View
+    */
     public function getEdit($consumableId = null)
     {
         // Check if the consumable exists
@@ -133,23 +140,22 @@ class ConsumablesController extends Controller
 
 
     /**
-     * Consumable update form processing page.
+    * Returns a form view to edit a consumable.
-     *
+    *
-     * @param  int  $consumableId
+    * @author [A. Gianotto] [<snipe@snipe.net>]
-     * @return Redirect
+    * @param  int $consumableId
-     */
+    * @see ConsumablesController::getEdit() method that stores the form data.
+    * @since [v1.0]
+    * @return Redirect
+    */
     public function postEdit($consumableId = null)
     {
-        // Check if the blog post exists
         if (is_null($consumable = Consumable::find($consumableId))) {
-            // Redirect to the blogs management page
             return Redirect::to('admin/consumables')->with('error', Lang::get('admin/consumables/message.does_not_exist'));
         } elseif (!Company::isCurrentUserHasAccess($consumable)) {
             return Redirect::to('admin/consumables')->with('error', Lang::get('general.insufficient_permissions'));
         }
 
-
-        // Update the consumable data
         $consumable->name                   = e(Input::get('name'));
         $consumable->category_id            = e(Input::get('category_id'));
         $consumable->location_id            = e(Input::get('location_id'));
@@ -171,25 +177,22 @@ class ConsumablesController extends Controller
 
         $consumable->qty                    = e(Input::get('qty'));
 
-        // Was the consumable created?
         if ($consumable->save()) {
-            // Redirect to the new consumable page
             return Redirect::to("admin/consumables")->with('success', Lang::get('admin/consumables/message.update.success'));
         }
 
         return Redirect::back()->withInput()->withErrors($consumable->getErrors());
 
-
-
-
     }
 
     /**
-     * Delete the given consumable.
+    * Delete a consumable.
-     *
+    *
-     * @param  int  $consumableId
+    * @author [A. Gianotto] [<snipe@snipe.net>]
-     * @return Redirect
+    * @param  int $consumableId
-     */
+    * @since [v1.0]
+    * @return Redirect
+    */
     public function getDelete($consumableId)
     {
         // Check if the blog post exists
@@ -210,14 +213,17 @@ class ConsumablesController extends Controller
 
 
     /**
-    *  Get the consumable information to present to the consumable view page
+    * Return a view to display component information.
     *
-    * @param  int  $consumableId
+    * @author [A. Gianotto] [<snipe@snipe.net>]
+    * @see ConsumablesController::getDataView() method that generates the JSON response
+    * @since [v1.0]
+    * @param int $consumableId
     * @return View
-    **/
+    */
-    public function getView($consumableID = null)
+    public function getView($consumableId = null)
     {
-        $consumable = Consumable::find($consumableID);
+        $consumable = Consumable::find($consumableId);
 
         if (isset($consumable->id)) {
 
@@ -239,8 +245,14 @@ class ConsumablesController extends Controller
     }
 
     /**
-    * Check out the consumable to a person
+    * Return a view to checkout a consumable to a user.
-    **/
+    *
+    * @author [A. Gianotto] [<snipe@snipe.net>]
+    * @see ConsumablesController::postCheckout() method that stores the data.
+    * @since [v1.0]
+    * @param int $consumableId
+    * @return View
+    */
     public function getCheckout($consumableId)
     {
         // Check if the consumable exists
@@ -259,8 +271,14 @@ class ConsumablesController extends Controller
     }
 
     /**
-    * Check out the consumable to a person
+    * Saves the checkout information
-    **/
+    *
+    * @author [A. Gianotto] [<snipe@snipe.net>]
+    * @see ConsumablesController::getCheckout() method that returns the form.
+    * @since [v1.0]
+    * @param int $consumableId
+    * @return Redirect
+    */
     public function postCheckout($consumableId)
     {
       // Check if the consumable exists
@@ -360,6 +378,15 @@ class ConsumablesController extends Controller
     }
 
 
+    /**
+    * Returns the JSON response containing the the consumables data.
+    *
+    * @author [A. Gianotto] [<snipe@snipe.net>]
+    * @see ConsumablesController::getIndex() method that returns the view that consumes the JSON.
+    * @since [v1.0]
+    * @param int $consumableId
+    * @return View
+    */
     public function getDatatable()
     {
         $consumables = Consumable::select('consumables.*')->whereNull('consumables.deleted_at')
@@ -431,7 +458,16 @@ class ConsumablesController extends Controller
 
     }
 
-    public function getDataView($consumableID)
+    /**
+    * Returns a JSON response containing details on the users associated with this consumable.
+    *
+    * @author [A. Gianotto] [<snipe@snipe.net>]
+    * @see ConsumablesController::getView() method that returns the form.
+    * @since [v1.0]
+    * @param int $consumableId
+    * @return View
+    */
+    public function getDataView($consumableId)
     {
         //$consumable = Consumable::find($consumableID);
         $consumable = Consumable::with(array('consumableAssigments'=>
@@ -442,7 +478,7 @@ class ConsumablesController extends Controller
         },
         'consumableAssigments.user'=> function ($query) {
         },
-        ))->find($consumableID);
+        ))->find($consumableId);
 
   //  $consumable->load('consumableAssigments.admin','consumableAssigments.user');