Merge branch 'feature/documentation' into develop

Documentation is finished, it's time to run the CI/CD flow

eight_queens/lib/main.dart

@@ -52,6 +52,10 @@ class _MyHomePageState extends State<MyHomePage> {
     super.dispose();
   }
 
+  ///
+  /// Creates a simple Dialog to show a message
+  /// Receives a [String] title and a [String] message to display a [AlertDialog]
+  ///
   void _showDialogBuilder(String title, String message) {
     showDialog(context: context,builder: (BuildContext context){
       return AlertDialog(
@@ -79,10 +83,11 @@ class _MyHomePageState extends State<MyHomePage> {
     super.initState();
   }
 
-  /**
-   * Retrieve the board number and pass it to the eight queens controller
-   * TODO: Create the Responsible class in Dart
-   */
+  ///
+  /// This method retrieves the [boardController.text] and checks if [isNumeric] and [boardController.text.isEmpty].
+  /// Then, it shows a [ProgressDialog] element while [QueenResolver] is executed.
+  /// Once a [count] is retrieved, we [Navigator.push] to [ResultsPage]
+  ///
   void _startProcessing() async {
 
     if(boardController.text.isEmpty){

eight_queens/lib/queens.dart

@@ -1,14 +1,19 @@
-/**
- * Queen Resolver class
- * Solved using algorithm found in: https://www.geeksforgeeks.org/n-queen-problem-using-branch-and-bound/
- */
+///
+///Queen Resolver class
+///Solved using algorithm found in: https://www.geeksforgeeks.org/n-queen-problem-backtracking-3/
+///Adapted for use with Dart and Flutter
+///
 
 import 'package:shared_preferences/shared_preferences.dart';
 
 class QueenResolver {
 
   int count = 0;
 
+  ///
+  /// Checks if a queen can be placed on a [board] in a [row] and [col]
+  /// Returns a [bool] if it's safe to place it [true] or not [false]
+  ///
   Future<bool> isSafe(board, int row, int col, int n) async {
       // Check row on the left side
       for (var i = 0; i < col; i++) {
@@ -40,8 +45,15 @@ class QueenResolver {
       return true;
   }
 
+  ///
+  /// Main eight queens algorithm
+  /// Receives a single [board] and [col] positions, as well as [n] queens.
+  /// Will return [true] when solved.
+  ///
   Future<bool> solveQueens(board, int col, int n) async {
 
+    /* Solve for the base case : All queens are placed
+    * Then, store it into local storage */
     if (col >= n) {
       count++;
       storeSolution(board).then((value) {
@@ -50,6 +62,7 @@ class QueenResolver {
     }
 
     var res = false;
+    /** Consider the [col] and try placing it on the [board] **/
     for(int i = 0; i < n; i++) {
       if(await isSafe(board, i, col, n)){
         board[i][col] = 1;
@@ -59,7 +72,10 @@ class QueenResolver {
     }
     return res;
   }
-
+
+  /// Stores a complete [board] into [SharedPreferences]
+  /// Because the [board] is not completely initialized, it requires to convert all [null] values to [0].
+  /// Stores also the current [count] into [SharedPreferences]
   Future storeSolution(List<List<int>> board) async {
     for(int i = 0; i < board.length; i++) {
       for(int x = 0; x < board[i].length ; x++) {
@@ -73,6 +89,10 @@ class QueenResolver {
     await prefs.setInt('count', count);
   }
 
+  ///
+  /// Function entryway to solve for [n] queens.
+  /// Will return [count] for the app's purposes
+  ///
   Future<int> solve(int n) async {
     // Create the initial queens board
      List<List<int>> board = new List.generate(n, (_) => new List(n));

eight_queens/lib/results.dart

@@ -1,4 +1,5 @@
 
+import 'package:eight_queens/queens.dart';
 import 'package:flutter/material.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 import 'dart:convert';
@@ -15,6 +16,11 @@ class ResultsPage extends StatefulWidget {
 class _ResultsPageState extends State<ResultsPage> {
   var boards = new List();
 
+  ///
+  /// Retrieves the [QueenResolver] [boards] that were calculated.
+  /// Will call [SharedPreferences] and get [String] for every posible solution.
+  /// Will then append it to [boards] and [setState()]
+  ///
   Future retrieveEightQueensResults() async {
     final prefs = await SharedPreferences.getInstance();
     var _boards = new List();
@@ -36,7 +42,11 @@ class _ResultsPageState extends State<ResultsPage> {
       super.initState();
     });
   }
-
+
+  ///
+  /// Simple Item builder to display a [board]
+  /// Uses [String] concatenation to make it work
+  ///
   Widget ResultItem(BuildContext context, int index) {
     String todisplay = "";
     for(int x = 0; x < boards[index].length; x++ ){