Docstring

"""
    generate_map function

    Generates a MineSweeper map within given parameters using a custom algorithm.

    This generator has implemented some debugging and anti-hung tools to make computationally
    secure generations and easily modifiable algorithms.

    Algorithm
    ---------

        This algorithm `does not check if` the generated map `has at least one solution`,
        as in the original game. Instead, it checks a series of conditions for each mine placed using
        recursive methods.

        For each mine to be placed, the steps below are followed:

        - First, a `cell is randomly chosen` considering the entire grid. Fails and tries again if the cell is not empty.

        - Second, the `range of all contiguous cells` to the chosen cell is computed. Then each contiguous cell
        is iterated and checked. `Two main conditions` are checked, the number of surrounding `valid empty cells` and
        if every surrounding `mine is still valid` if the current one were placed. If one of the conditions fails,
        then the cell is discarded as invalid and failed attempts counter increases by one.

        - A `valid empty cell` is one that is surrounded by at least `three empty cells`. Note that, due to recursive
        limit, the surrounding empty cells to the empty cell being checked are not also checked. This means that the
        surrounding empty cells to the empty cell being checked could not have at least three surrounding empty cells.

        - A `valid mine` is one that has at least three surrounding `valid empty cells`. Note that, when three surrounding
        valid empty cells are already found while checking a mine, then no more empty cells will be checked,
        but mines will continue to be searched to validate.

        - When a `mine` is found while checking the surrounding cells, then that mine will be checked recursively having as a
        parent the mine before it. If another mine is found, then again it will be checked recursively having as parents the mines
        before it. This recursive search will stop if more than four cells are found straight, reaching the concatenated mine limit.
        Then the main parent cell that is being checked will be discarded as invalid for new mines.
        Note that the algorithm does not register which cells were discarded as invalid.
        So, if the same cell is chosen again, the recursive search will be performed again.

        - Finally, if all surrounding mines and those surrounding them are valid and the concatenated mine limit was not reached,
        the current checked cell will be set as a mine.

        - This process will stop in two cases. First, if no more mines have to be placed and all mines have been placed
        correctly. Second, if the failed attempts counter reaches a certain limit, by default 500. The failed attempts limit
        should be set larger if large grids with higher proportions of mines are computed.
"""