Documenting Controllers

app/Http/Controllers/CompanyController.php

@@ -19,12 +19,23 @@ use Crater\Currency;
 use Crater\CompanySetting;
 
 class CompanyController extends Controller
-{
+{   
+    /**
+     * Retrive the Admin account.
+     * @return \Crater\User
+     */
     public function getAdmin()
     {
         return User::find(1);
     }
 
+    /**
+     * Update the Admin profile.
+     * Includes name, email and (or) password
+     *
+     * @param  \Crater\Http\Requests\ProfileRequest $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function updateAdminProfile(ProfileRequest $request)
     {
         $verifyEmail = User::where('email', $request->email)->first();
@@ -54,6 +65,14 @@ class CompanyController extends Controller
         ]);
     }
 
+
+    
+    /**
+     * Get Admin Account alongside the country from the addresses table and 
+     * The company from companies table
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function getAdminCompany()
     {
         $user = User::with(['addresses', 'addresses.country', 'company'])->find(1);
@@ -63,6 +82,13 @@ class CompanyController extends Controller
         ]);
     }
 
+
+
+    /**
+     * Update Admin Company Details
+     * @param \Crater\Http\Requests\CompanyRequest $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function updateAdminCompany(CompanyRequest $request)
     {
         $user = User::find(1);
@@ -85,6 +111,11 @@ class CompanyController extends Controller
         ]);
     }
 
+    /**
+     * Retrieve General App Settings
+     * @param \Illuminate\Http\Request $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function getGeneralSettings(Request $request)
     {
         $date_formats = DateFormatter::get_list();
@@ -133,6 +164,13 @@ class CompanyController extends Controller
         ]);
     }
 
+
+
+    /**
+     * Update General App Settings
+     * @param \Crater\Http\Requests\CompanySettingRequest $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function updateGeneralSettings(CompanySettingRequest $request)
     {
         $sets = [
@@ -153,6 +191,11 @@ class CompanyController extends Controller
         ]);
     }
 
+    /**
+     * Update a specific Company Setting
+     * @param \Crater\Http\Requests\SettingRequest $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function updateSetting(SettingRequest $request)
     {
         CompanySetting::setSetting($request->key, $request->value, $request->header('company'));
@@ -162,6 +205,11 @@ class CompanyController extends Controller
         ]);
     }
 
+    /**
+     * Retrieve Specific Company Setting
+     * @param \Crater\Http\Requests\SettingKeyRequest $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function getSetting(SettingKeyRequest $request)
     {
         $setting = CompanySetting::getSetting($request->key, $request->header('company'));
@@ -171,6 +219,12 @@ class CompanyController extends Controller
         ]);
     }
 
+
+    /**
+     * Retrieve App Colors
+     * @param \Illuminate\Http\Request $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function getColors(Request $request)
     {
         $colors = [
@@ -205,7 +259,7 @@ class CompanyController extends Controller
      * Upload the company logo to storage.
      *
      * @param  \Illuminate\Http\Request $request
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function uploadCompanyLogo(Request $request)
     {
@@ -232,7 +286,7 @@ class CompanyController extends Controller
      * Upload the Admin Avatar to public storage.
      *
      * @param  \Illuminate\Http\Request $request
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function uploadAdminAvatar(Request $request)
     {

app/Http/Controllers/CustomersController.php

@@ -19,7 +19,7 @@ class CustomersController extends Controller
     /**
      * Display a listing of the resource.
      *
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function index(Request $request)
     {
@@ -53,7 +53,7 @@ class CustomersController extends Controller
      * Store a newly created resource in storage.
      *
      * @param  \Illuminate\Http\Request  $request
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function store(Requests\CustomerRequest $request)
     {
@@ -104,7 +104,7 @@ class CustomersController extends Controller
      * Display the specified resource.
      *
      * @param  int  $id
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function show($id)
     {
@@ -124,7 +124,7 @@ class CustomersController extends Controller
      * Show the form for editing the specified resource.
      *
      * @param  int  $id
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function edit($id)
     {
@@ -144,7 +144,7 @@ class CustomersController extends Controller
      *
      * @param  \Illuminate\Http\Request  $request
      * @param  int  $id
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function update($id, Requests\CustomerRequest $request)
     {
@@ -203,10 +203,10 @@ class CustomersController extends Controller
     }
 
     /**
-     * Remove the specified resource from storage.
+     * Remove the specified Customer along side all his/her resources (ie. Estimates, Invoices, Payments and Addresses)
      *
      * @param  int  $id
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function destroy($id)
     {
@@ -217,6 +217,13 @@ class CustomersController extends Controller
         ]);
     }
 
+
+    /**
+     * Remove a list of Customers along side all their resources (ie. Estimates, Invoices, Payments and Addresses)
+     *
+     * @param  \Illuminate\Http\Request $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function delete(Request $request)
     {
         foreach ($request->id as $id) {

app/Http/Controllers/DashboardController.php

@@ -15,6 +15,12 @@ use Illuminate\Support\Facades\DB;
 
 class DashboardController extends Controller
 {
+
+    /**
+     * Retrieve Dashboard details
+     * @param \Illuminate\Http\Request $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function index(Request $request)
     {
         $invoiceTotals = [];
@@ -137,6 +143,11 @@ class DashboardController extends Controller
         ]);
     }
 
+    /**
+     * Retrive Expense Chart data
+     * @param \Illuminate\Http\Request $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function getExpenseChartData(Request $request)
     {
         $expensesCategories = Expense::with('category')

app/Http/Controllers/ExpensesController.php

@@ -17,7 +17,7 @@ class ExpensesController extends Controller
     /**
      * Display a listing of the resource.
      *
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function index(Request $request)
     {
@@ -48,7 +48,7 @@ class ExpensesController extends Controller
     /**
      * Show the form for creating a new resource.
      *
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function create(Request $request)
     {
@@ -63,7 +63,7 @@ class ExpensesController extends Controller
      * Store a newly created resource in storage.
      *
      * @param  \Illuminate\Http\Request $request
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function store(ExpenseRequest $request)
     {
@@ -91,7 +91,7 @@ class ExpensesController extends Controller
      * Display the specified resource.
      *
      * @param  \Crater\Expense $expense
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function show(Expense $expense)
     {
@@ -102,7 +102,7 @@ class ExpensesController extends Controller
      * Show the form for editing the specified resource.
      *
      * @param  $id
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function edit(Request $request,$id)
     {
@@ -122,7 +122,7 @@ class ExpensesController extends Controller
      *
      * @param  \Illuminate\Http\Request $request
      * @param  \Crater\Expense $expense
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function update(ExpenseRequest $request, Expense $expense)
     {
@@ -150,7 +150,7 @@ class ExpensesController extends Controller
      * Remove the specified resource from storage.
      *
      * @param  \Crater\Expense $expense
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function destroy(Expense $expense)
     {
@@ -175,7 +175,7 @@ class ExpensesController extends Controller
      *
      * @param  \Illuminate\Http\Request $request
      * @param   $id
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function uploadReceipts(Request $request, $id)
     {
@@ -200,6 +200,12 @@ class ExpensesController extends Controller
         ]);
     }
 
+
+    /**
+     * Retrive details of an expense receipt from storage.
+     * @param   int $id
+     * @return  \Illuminate\Http\JsonResponse
+     */ 
     public function showReceipt($id)
     {
         $expense = Expense::find($id);
@@ -226,6 +232,14 @@ class ExpensesController extends Controller
         ]);
     }
 
+
+
+    /**
+     * Download an expense receipt from storage.
+     * @param   int $id
+     * @param   strig $hash
+     * @return  \Symfony\Component\HttpFoundation\BinaryFileResponse | \Illuminate\Http\JsonResponse
+     */    
     public function downloadReceipt($id, $hash)
     {
         $company = Company::where('unique_hash', $hash)->first();

app/Http/Controllers/FrontendController.php

@@ -118,6 +118,11 @@ class FrontendController extends Controller
         return $pdf->stream();
     }
 
+
+    /**
+    *
+     * @return \Illuminate\Http\Response
+     */
     public function getCustomerInvoicePdf($id)
     {
         $invoice = Invoice::with([

app/Http/Controllers/InvoicesController.php

@@ -27,7 +27,7 @@ class InvoicesController extends Controller
     /**
      * Display a listing of the resource.
      *
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function index(Request $request)
     {
@@ -60,7 +60,7 @@ class InvoicesController extends Controller
     /**
      * Show the form for creating a new resource.
      *
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function create(Request $request)
     {
@@ -81,7 +81,7 @@ class InvoicesController extends Controller
      * Store a newly created resource in storage.
      *
      * @param  \Illuminate\Http\Request $request
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function store(Requests\InvoicesRequest $request)
     {
@@ -185,7 +185,7 @@ class InvoicesController extends Controller
      * Display the specified resource.
      *
      * @param  int $id
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function show(Request $request, $id)
     {
@@ -209,7 +209,7 @@ class InvoicesController extends Controller
      * Show the form for editing the specified resource.
      *
      * @param  int $id
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function edit(Request $request,$id)
     {
@@ -236,7 +236,7 @@ class InvoicesController extends Controller
      *
      * @param  \Illuminate\Http\Request $request
      * @param  int $id
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function update(Requests\InvoicesRequest $request, $id)
     {
@@ -331,7 +331,7 @@ class InvoicesController extends Controller
      * Remove the specified resource from storage.
      *
      * @param  int $id
-     * @return \Illuminate\Http\Response
+     * @return \Illuminate\Http\JsonResponse
      */
     public function destroy($id)
     {
@@ -369,6 +369,14 @@ class InvoicesController extends Controller
         ]);
     }
 
+
+
+     /**
+     * Mail a specific invoice to the correponding cusitomer's email address.
+     *
+     * @param  \Illuminate\Http\Request $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function sendInvoice(Request $request)
     {
         $invoice = Invoice::findOrFail($request->id);
@@ -409,6 +417,13 @@ class InvoicesController extends Controller
         ]);
     }
 
+
+     /**
+     * Mark a specific invoice as sent.
+     *
+     * @param  \Illuminate\Http\Request $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function markAsSent(Request $request)
     {
         $invoice = Invoice::findOrFail($request->id);
@@ -421,6 +436,13 @@ class InvoicesController extends Controller
         ]);
     }
 
+
+     /**
+     * Mark a specific invoice as paid.
+     *
+     * @param  \Illuminate\Http\Request $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function markAsPaid(Request $request)
     {
         $invoice = Invoice::findOrFail($request->id);
@@ -434,6 +456,14 @@ class InvoicesController extends Controller
         ]);
     }
 
+
+     /**
+     * Retrive a specified user's unpaid invoices from storage.
+     *
+     * @param  \Illuminate\Http\Request $request
+     * @param  int $id
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function getCustomersUnpaidInvoices(Request $request, $id)
     {
         $invoices = Invoice::where('paid_status', '<>', Invoice::STATUS_PAID)

app/Http/Controllers/ItemsController.php

@@ -43,6 +43,13 @@ class ItemsController extends Controller
         ]);
     }
 
+
+     /**
+     * Create Item.
+     *
+     * @param  Crater\Http\Requests\ItemsRequest $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function store(Requests\ItemsRequest $request)
     {
         $item = new Item();
@@ -67,6 +74,13 @@ class ItemsController extends Controller
         ]);
     }
 
+    /**
+     * Update an existing Item.
+     *
+     * @param  Crater\Http\Requests\ItemsRequest $request
+     * @param int $id
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function update(Requests\ItemsRequest $request, $id)
     {
         $item = Item::find($id);
@@ -96,6 +110,13 @@ class ItemsController extends Controller
         ]);
     }
 
+
+    /**
+     * Delete an existing Item.
+     *
+     * @param int $id
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function destroy($id)
     {
         $data = Item::deleteItem($id);
@@ -111,6 +132,14 @@ class ItemsController extends Controller
         ]);
     }
 
+
+
+    /**
+     * Delete a list of existing Items.
+     *
+     * @param  \Illuminate\Http\Request $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function delete(Request $request)
     {
         $items = [];

app/Http/Controllers/LocationController.php

@@ -6,6 +6,12 @@ use Crater\Country;
 
 class LocationController extends Controller
 {
+
+    /**
+     * Retrive a list of Countries.
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function getCountries()
     {
         return response()->json([

app/Http/Controllers/OnboardingController.php

@@ -18,6 +18,13 @@ use Illuminate\Support\Facades\Artisan;
 
 class OnboardingController extends Controller
 {
+
+    /**
+     * Retrieve Onboarding data.
+     *
+     * @param  \Illuminate\Http\Request $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function getOnboardingData(Request $request)
     {
         if (!\Storage::disk('local')->has('database_created')) {
@@ -72,6 +79,13 @@ class OnboardingController extends Controller
         ]);
     }
 
+
+    /**
+     * Setup Admin Profile.
+     *
+     * @param  \Crater\Http\Requests\ProfileRequest $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function adminProfile(ProfileRequest $request)
     {
         $setting = Setting::getSetting('profile_complete');
@@ -97,6 +111,12 @@ class OnboardingController extends Controller
         ]);
     }
 
+    /**
+     * Setup Admin Avatar.
+     *
+     * @param  \Illuminate\Http\Request $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function uploadAdminAvatar(Request $request)
     {
         $setting = Setting::getSetting('profile_complete');
@@ -123,6 +143,12 @@ class OnboardingController extends Controller
         ]);
     }
 
+    /**
+     * Setup Admin Company.
+     *
+     * @param  \Crater\Http\Requests\CompanyRequest $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function adminCompany(CompanyRequest $request)
     {
         $setting = Setting::getSetting('profile_complete');
@@ -174,6 +200,13 @@ class OnboardingController extends Controller
         ]);
     }
 
+
+    /**
+     * Setup Company Settings.
+     *
+     * @param  \Crater\Http\Requests\CompanySettingRequest $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function companySettings(CompanySettingRequest $request)
     {
         $setting = Setting::getSetting('profile_complete');

app/Http/Controllers/SettingsController.php

@@ -7,6 +7,13 @@ use Crater\Setting;
 
 class SettingsController extends Controller
 {
+
+    /**
+     * Retrive App Version.
+     *
+     * @param  \Illuminate\Http\Request $request
+     * @return \Illuminate\Http\JsonResponse
+     */
     public function getAppVersion(Request $request)
     {
         $version = Setting::getSetting('version');