Added comments

Author: labmonkey

app/Http/Controllers/HistoryController.php

@@ -14,20 +14,23 @@
 use Illuminate\Foundation\Auth\Access\AuthorizesResources;
 use App\History;
 use Illuminate\Http\Request;
-use App\Libraries\Converter;
 
 class HistoryController extends BaseController {
 	use AuthorizesRequests, AuthorizesResources, DispatchesJobs, ValidatesRequests;
 
 	function convert( Request $request ) {
+		// built-in validation
 		$this->validate( $request, [
 			'number' => 'required|numeric|min:0|max:3999',
 		] );
 
+		// log this request into database
 		$history         = new History;
 		$history->number = $request->number;
 		$history->save();
 
+		// redirect to 'home' route with query string 'number'.
+		// It's GET request which will show the resulting number in decimal na roman
 		return redirect( route( 'home', array( 'number' => $request->number ) ) );
 	}
 }

app/Http/Controllers/HomeController.php

@@ -19,19 +19,24 @@
 class HomeController extends BaseController {
 	use AuthorizesRequests, AuthorizesResources, DispatchesJobs, ValidatesRequests;
 
+	/*
+	 * Displays the homepage
+	 */
 	function index( Request $request ) {
 		$history = History::orderBy( 'created_at', 'desc' )->get();
 
 		$data = array(
 			'history' => $history
 		);
 
+		// If there was 'number' param then show both decimal and roman numbers in their fields
 		if ( $request->number ) {
 			$converter      = new Converter();
 			$data['number'] = $request->number;
 			$data['roman']  = $converter->toRomanNumerals( $request->number );
 		}
 
+		// used when converting numbers in template when displaying history
 		$data['converter'] = new Converter();
 
 		return view( 'converter', $data );

app/Http/routes.php

@@ -13,8 +13,7 @@
 
 Route::get( '/', [ 'as' => 'home', 'uses' => 'HomeController@index' ] );
 
-
 /**
- * Add New History
+ * Add New History item
  */
 Route::post( '/history', [ 'as' => 'history', 'uses' => 'HistoryController@convert' ] );

app/Libraries/Converter.php

@@ -13,7 +13,11 @@
 
 class Converter implements IntegerConversion {
 
+	/*
+	 * Validate and convert
+	 */
 	public function convert( $number ) {
+		// standalone validator with default settings
 		$factory    = new ValidatorFactory( new Translator( 'en' ) );
 		$validation = $factory->make(
 			array(
@@ -31,6 +35,9 @@ public function convert( $number ) {
 		return $this->toRomanNumerals( $number );
 	}
 
+	/*
+	 * Convert number into roman numeral
+	 */
 	public function toRomanNumerals( $number ) {
 		$result = '';
 		$number = (int) $number;
@@ -40,6 +47,8 @@ public function toRomanNumerals( $number ) {
 			return false;
 		}
 
+		// Dictionary contains only the basic numbers and the
+		// rest is calculated basing on it
 		$dictionary = array(
 			1    => 'I',
 			5    => 'V',
@@ -50,30 +59,45 @@ public function toRomanNumerals( $number ) {
 			1000 => 'M'
 		);
 
-		// end early if key exists
+		// end early if key already exists
 		if ( array_key_exists( $number, $dictionary ) ) {
 			return $dictionary[ $number ];
 		}
 
+		// used for $part calculation (more description in loop)
 		$temp = 0;
 
+		/*
+		 * The idea here is to split numbers into chunks so for ex. '1345' becomes 1000, 300, 40, 5
+		 * and then each chunk is looked up in dictionary.
+		 */
 		for ( $i = 1000; (int) $i !== 0; $i /= 10 ) {
+			// current chunk is the difference of given number, $i
+			// and sum of previous chunks from the loop
 			$part = $number - ( (int) $number % $i ) - $temp;
 
+			// don't calculate when it's not needed
+			// for ex. 45 doesn't need '1000' chunk
+			// and when there are no chunks left we can break
 			if ( $i > $number || $part == 0 ) {
 				continue;
 			}
 
 			$closest = $this->closest( $dictionary, $part );
+
+			// either number is closer to prev character in dictionary or to next one
 			if ( $closest < $part ) {
+				// numbers that are lower can have repeated character ( like I, II, III)
 				$repeat = floor( $part / $closest );
 				$result .= str_repeat( $dictionary[ $closest ], $repeat );
 
+				// should there be something appended (like to V : VI, VII)
 				$after = $this->toRomanNumerals( $part - ( $closest * $repeat ) );
 				if ( $after ) {
 					$result .= $after;
 				}
 			} else {
+				// should there be something prepended (like to V : IV)
 				$before = $this->toRomanNumerals( $closest - $part );
 				if ( $before ) {
 					$result .= $before;
@@ -82,20 +106,30 @@ public function toRomanNumerals( $number ) {
 				$result .= $dictionary[ $closest ];
 			}
 
+			// sum of all previous chunks
 			$temp += $part;
 		}
 
 		return $result;
 	}
 
 	function closest( $array, $number ) {
+		/*
+		 * This ratio was taken from the overall idea how roman numbers work.
+		 * For ex. after I there are 2 numbers that append it and before V there is one that prepends is.
+		 * It works same way for all other roman letters/numbers. The point at which this 'switch' happens
+		 * is exactly after third of all numbers (I, II, III, IV, V) so it happens at fourth of 5 numbers.
+		 * It's position is 4/5 which translates into 0.8.
+		 */
 		$ratio = 0.8;
 
+		// get the last and first element of array
 		end( $array );
 		$next = key( $array );
 		reset( $array );
 		$prev = key( $array );
 
+		// this way we know which element is before and after the given number
 		foreach ( $array as $key => $val ) {
 			if ( $key > $number ) {
 				$next = $key;
@@ -104,10 +138,12 @@ function closest( $array, $number ) {
 			$prev = $key;
 		}
 
+		// if the number is closer to the next roman number (IV closer to V)
 		if ( $number / $next >= $ratio ) {
 			return $next;
 		}
 
+		// number was closer to previous number (II, III closer to I)
 		return $prev;
 	}
 }

public/js/app.js

@@ -24,4 +24,15 @@ The theme is built using gulp, elixir ans scss. It's designed with simplicity in
 - When submitted the form should display both the integer and roman numeral
   values
 - Support numbers between 0 and 3999, only numeric characters
-- Display history of converted numbers along with creation time
+- Display history of converted numbers along with creation time
+
+### Important custom files
+
+- `app/Http/routes.php`
+- `app/Http/Controllers`
+- `app/Http/Libraries`
+- `app/History.php`
+- `config/app.php` (Include Laravel Collective library Classes)
+- `resources/assets` (Sass, JS)
+- `resources/views` (Blade templates)
+- `tests/ConverterTest.php`

public/js/app.js.map

@@ -1 +1,2 @@
+// import jQuery via browserify
 window.$ = window.jQuery = require('jquery');