Consertando documentação

renzon · renzon · commit 84e75e5c44da · 2014-11-12T21:06:00.000-02:00
diff --git a/README.md b/README.md
@@ -55,12 +55,12 @@ Contém lógica para rodar jogo e exibir no console.
 
 ## script placa_grafica_tkinter.py
 
-Contém lógica para rodar jogo e em uma janela.
+Contém lógica para rodar jogo em uma janela.
 
 # Simplificação do Jogo
 
 1. Atores são pontos no plano cartesiano. 
-2. A velocidade dos pontos e pequena, de tal forma que a cada passo os atores se movam apenas para pontos vizinhos.
+2. A velocidade dos pontos é pequena, de tal forma que a cada passo os atores se movam apenas para pontos vizinhos.
 3. A colisão entre pontos ocorre quando eles estão em ponto vizinho, de acordo com valor de intervalo.
 
 A seguir é apresentada a especificação detalhada do jogo.
@@ -77,12 +77,12 @@ primeiro elemento e posição vertical (y) como segundo.
 ### Método colidir
 
 O método colidir executa a lógica de colisão. A colisão só ocorre com atores ativos e que estejam
-em pontos vizinhos. 
+em pontos vizinhos. Ao colidir, os atores envolvidos devem ter seus status alterado para DESTRUIDO
 
 ## Classe Obstaculo
 
-Classe que representa obstáculos na fase e que podem ser destruidos por pássaros. Herda de ator. Seu caracter de 
-representação é a letra "O" quando Ativo.
+Classe que representa obstáculos na fase e que podem ser destruídos por pássaros. Herda de ator. Seu caracter de 
+representação é a letra "O", quando ATIVO.
 
 ### Status
 
@@ -91,9 +91,14 @@ Assim ele vai "sumir" da tela.
 
 ## Classe Porco
 
-Classe que representa porcos na fase e que podem ser destruidos por pássaros. Herda de ator. Seu caracter de 
+Classe que representa porcos na fase e que podem ser destruídos por pássaros. Herda de ator. Seu caracter de 
 representação é a o caracter "@".
 
+### Status
+
+Um obstáculo ao ter seu status alterado para DESTRUIDO deve ter seu caracter de apresentação alterado para "+" (sinal de mais).
+Assim sua imagem é alterada para a de porco morto.
+
 ## Passaro
 
 Classe base de todos os passáros. Cada tipo possui uma velocidade de lançamento (v). No lançamento o jogador escolhe o 
@@ -102,8 +107,9 @@ gravidade (GRAVIDADE) constante e igual a 10 m/s^2.
 
 ### Método lancar
 
-O método lançar recebe o ângulo, em graus, que será feito o lançamento. Cada pássaro deve armazenar esse valor e o tempo
-de lançamento para cálculo de sua posíção. Lembrar que o tempo das fórmulas é delta_t = T_final - T_inicial
+O método lançar recebe o ângulo, em graus, que será feito o lançamento. Ele deve ser convertido para radianos.
+Cada pássaro deve armazenar esse valor e o tempo
+de lançamento para cálculo de sua posíção. Lembrar que o tempo das fórmulas é delta_t = T_final - T_inicial.
 
 
 ### Método de colidir_com_chao
@@ -113,13 +119,13 @@ Todo pássaro que colidir com o chão (y<=0) deve ser destruído.
 ### Método foi_lançado
 
 Esse método deve retornar verdadadeiro se o pássaro foi lançado (tempo de lançamento é None).
-Caso contrário deve retornar falso
+Caso contrário deve retornar falso.
 
 ### Lançamento
 
 Se o pássaro ainda não foi lançado, o pássaro deve permanecer na posição inicial.
   
-Caso tenha sido lançado e seu status esteja ativo, sua posição deve ser calculada de acordo com o lançamento oblíquo.
+Caso tenha sido lançado e seu status esteja ATIVO, sua posição deve ser calculada de acordo com o lançamento oblíquo.
 Nesse caso, delta_t vai ser igual ao tempo do jogo menos o tempo do lançamento.
   
 Caso contrário, ele deve retornar a posição onde colidiu.
@@ -143,39 +149,32 @@ Tipo de Pássaro que representa o pássaro amarelo. Possui velocidade de lançam
 
 ## Classe Fase
 
-Classe responsável por organizar atores e transformarem os dados em pontos a serem representados na tela.
+Classe responsável por organizar atores e transformar os dados em pontos a serem representados na tela.
 
 ### Método adicionar_obstaculo
 
-Método que adiciona um ou mais obstáculos na fase
+Método que adiciona um ou mais obstáculos na fase.
 
 ### Método adicionar_porco
 
-Método que adiciona um ou mais porcos na fase
+Método que adiciona um ou mais porcos na fase.
 
 ### Método adicionar_passaro
 
-Método que adiciona um ou mais pássaros na fase
-
-### Método acabou
-
-Método que recebe o tempo do jogo e retorna verdadeiro (True) se o jogo acabou e (False) caso contrário.
-O jogo pode acabar por duas razôes:
+Método que adiciona um ou mais pássaros na fase.
 
-1. Todos porcos foram destruídos
-2. Não há mais pássaros a serem lançados
 
 ### Método status
 
-Recebe o tempo como parâmetro e retorna mensagem com status do jogo.
+Recebe o tempo como parâmetro e retorna status do jogo.
 
-1. Se o jogo está em andamento, retorna mensagem "Jogo em andamento."
-2. Se o jogo acabou e não existem porcos ativos, retorna a mensagem "Jogo em encerrado. Você ganhou!"
-3. Se o jogo acabou e existem porcos ativos, retorna a mensagem "Jogo em encerrado. Você perdeu!"
+1. Se o jogo está em andamento, retorna status "EM_ANDAMENTO";
+2. Se o jogo acabou e não existem porcos ativos, retorna STATUS "VITORIA";
+3. Se o jogo acabou e existem porcos ativos, retorna status "DERROTA".
 
 ### Método lancar
 
-Recebe o ângulo e o tempo do lançamento. Deve delegar o lançamento ao primeiro pássaro ativo da lista de pássaros que 
+Recebe o ângulo e o tempo do lançamento. Deve delegar o lançamento ao primeiro pássaro ATIVO da lista de pássaros que 
 ainda não foi lançado.
 
 ### Método calcular_pontos
@@ -185,7 +184,7 @@ Método que executa a lógica do jogo a cada passo (tempo), retornando pontos a
 Ele deve:
 
 1. Calcular a posição de cada pássaro, verificando se ele colidiu com algum obstáculo, porco ou chão.
-2. Retornar instâncias da classe Ponto, informando x,y e caracter respectivo a cada ator.
+2. Retornar instâncias da classe Ponto, informando x, y e caracter respectivo a cada ator.
 
 ### Divirta-se!!!!
 
diff --git a/testes/atores_testes.py b/testes/atores_testes.py
@@ -7,13 +7,15 @@
 
 class AtorTestes(TestCase):
     def teste_valores_padrao(self):
+        'Testa valores iniciais padrão de um Ator'
         ator = Ator()
         self.assertEqual(0, ator.x)
         self.assertEqual(0, ator.y)
         self.assertEqual(ATIVO, ator.status)
         self.assertEqual('A', ator.caracter())
 
     def teste_valores_passados_por_parametro(self):
+        'Testa se valores passados no inicializador são armazenados no objeto'
         ator = Ator(1, 2)
         self.assertEqual(1, ator.x)
         self.assertEqual(2, ator.y)
@@ -34,6 +36,12 @@ def teste_ator_posicao(self):
 
 
     def teste_colisao_entre_atores_ativos(self):
+        """
+        Teste de colisão entre dois atores
+        Incialmente atores possuem status ATIVO. Ao se chocarem, ele muda para Destruído
+        A função assert_colisao_atores_ativos testa justamente se dois atore ativos se chocam quando estão em posições
+        vizinhas.
+        """
         ator = Ator(2, 2)  # Ator recém criado deve ter status ativo
         ator2 = Ator(2, 2)
         self.assert_colisao_atores_ativos(ator, ator2)
@@ -51,6 +59,7 @@ def teste_colisao_entre_atores_ativos_com_intervalo(self):
         self.assert_colisao_atores_ativos(Ator(2, 2), Ator(2, 4), 2)
 
     def teste_nao_colisao_entre_atores_ativos(self):
+        'Teste de que não há colisão entre atores distantes'
         self.assert_nao_colisao(Ator(2, 2), Ator(2, 4))
         self.assert_nao_colisao(Ator(2, 2), Ator(3, 4))
         self.assert_nao_colisao(Ator(2, 2), Ator(4, 2))
@@ -61,8 +70,9 @@ def teste_nao_colisao_entre_atores_ativos(self):
         self.assert_nao_colisao(Ator(2, 2), Ator(0, 4))
 
     def teste_colisao_somente_um_ator_destruido(self):
+        'Teste de que um ator destruído não pode colidir com nenhum outro, mesmo que estejam próximos'
         ator = Ator(2, 2)
-        ator.colidir(ator, 0)  # colidingo ator com ele mesmo para alterar seu status para destruido
+        ator.colidir(ator, 0)  # colidindo ator com ele mesmo para alterar seu status para destruido
         ator2 = Ator(2, 2)
         self.assert_nao_colisao(ator, ator2)
         self.assert_nao_colisao(Ator(2, 3), ator)
@@ -84,6 +94,7 @@ def teste_colisao_somente_um_ator_destruido(self):
         self.assert_nao_colisao(Ator(1, 3), ator)
 
     def test_caracter(self):
+        'Teste de caracter para status ATIVO e DESTRUIDO'
         ator = Ator()
         self.assertEqual('A', ator.caracter())
         outro_ator_na_mesma_posicao = Ator()
@@ -92,7 +103,11 @@ def test_caracter(self):
 
 
     def assert_colisao_atores_ativos(self, ator, ator2, intervalo=1):
-        'Se certifica que há colisão entre atores ativos'
+        """
+        Se certifica que há colisão entre atores ativos
+        Atenção: Esse não é método de teste porque nao se inicia com prefixo "text".
+        Ele serve apenas para encapsular toda lógica de teste de colisão entre dois atores ativos
+        """
         # Conferindo status dos dois atores antes da colisão
         self.assertEqual(ator.status, ATIVO, 'Status deveria ser ativo antes da colisão')
         self.assertEqual(ator2.status, ATIVO, 'Status deveria ser ativo antes da colisão')
@@ -102,7 +117,12 @@ def assert_colisao_atores_ativos(self, ator, ator2, intervalo=1):
         self.assertEqual(ator.status, DESTRUIDO, 'Status deveria ser destruido depois da colisão')
 
     def assert_nao_colisao(self, ator, ator2):
-        'Se certifica que não colisão entre dois atores'
+        """
+        Se certifica que não colisão entre dois atores
+        Atenção: Esse não é método de teste porque nao se inicia com prefixo "text".
+        Ele apenas encapsula a lógica de não colisão entre dois atores.
+        So seja, eles deve manter seus respectivos status mesmo depois da chamada do metodo colidir
+        """
         # Armazenando status antes da colisão
         status_inicial_ator = ator.status
         status_inicial_ator_2 = ator2.status
@@ -133,14 +153,34 @@ def teste_status(self):
 
 
 class PassaroBaseTests(TestCase):
+    """
+    Classe base para teste de passaros.
+    Essa classe não contèm nenhum teste, serve apenas para encapsular a lógica de asserção de posição de passaros
+    vermelhos e também dos amarelos.
+
+    """
+
     def assert_passaro_posicao(self, x_esperado, y_esperado, status_esperado, passaro, tempo):
+        """
+        Mètodo que se testa posição do pássaro.
+        Atenção: Esse não é método de teste porque nao se inicia com prefixo "text".
+        :param x_esperado: posição x esperada do passaro
+        :param y_esperado: posição y esperada do passaro
+        :param status_esperado: status esperado do passaro
+        :param passaro: passaro alvo do teste
+        :param tempo: tempo do jogo
+        """
         x_calculado, y_calculado = passaro.calcular_posicao(tempo)
         self.assertEqual(x_esperado, round(x_calculado), 'valor real de x = %s' % x_calculado)
         self.assertEqual(y_esperado, round(y_calculado), 'valor real de y = %s' % y_calculado)
         self.assertEqual(status_esperado, passaro.status, '(x = %s, y = %s)' % (x_calculado, y_calculado))
 
 
 class PassaroVermelhoTests(PassaroBaseTests):
+    """
+    Classe de teste e Passaro Vermelho
+    """
+
     def teste_status(self):
         passaro_amarelo = PassaroVermelho(1, 1)
         self.assertEqual('V', passaro_amarelo.caracter())
@@ -154,6 +194,11 @@ def teste_velocidade_escalar(self):
 
 
     def teste_foi_lancado(self):
+        """
+        Teste de lançamento. Enquanto o método lançar do passaro não for chamado, o méotod foi_lancado deve retornar
+        Falso
+        :return:
+        """
         passaro_vermelho = PassaroVermelho(1, 1)
         self.assertFalse(passaro_vermelho.foi_lancado(),
                          'Se o método lançar ainda não foi executado, deve retornar falso')
@@ -162,6 +207,10 @@ def teste_foi_lancado(self):
                         'Se o método lançar foi executado, deve retornar verdadeiro')
 
     def teste_colisao_com_chao(self):
+        """
+        Testando que o passáro colido quando sua posição y é menor ou igual a 0
+        :return:
+        """
         passaro = PassaroVermelho(0, 0)
         passaro.colidir_com_chao()
         self.assertEqual(DESTRUIDO, passaro.status, 'Deve colidir com chão sempre que y<=0')
@@ -180,6 +229,10 @@ def teste_colisao_com_chao(self):
 
 
 class PassaroAmareloTests(PassaroBaseTests):
+    """
+    Classe de Tests para passaros amarelos
+    """
+
     def teste_status(self):
         passaro_amarelo = PassaroAmarelo(1, 1)
         self.assertEqual('A', passaro_amarelo.caracter())
@@ -191,54 +244,56 @@ def teste_velocidade_escalar(self):
         self.assertEqual(30, PassaroAmarelo.velocidade_escalar)
 
     def teste_lacamento_vertical(self):
+        """
+        Tests de lançamento vertical. Nele, o passaro só se move verticalmente e sua posição y se matém contanstante
+        :return:
+        """
         passaro_amarelo = PassaroAmarelo(1, 1)
         passaro_amarelo.lancar(90, 2)  # passaro lancado a 90 graus no tempo 2 segundos
 
-        # função auxiliar que mantém x fixo com valor 1, status Ativo, variando apenas o tempo e a posição y
-        def assert_vertical(y, tempo):
-            self.assert_passaro_posicao(1, y, ATIVO, passaro_amarelo, tempo)
+
 
         # subindo
 
-        assert_vertical(1, 2.0)
-        assert_vertical(1, 2.01)
-        assert_vertical(2, 2.02)
-        assert_vertical(2, 2.03)
-        assert_vertical(2, 2.04)
-        assert_vertical(2, 2.05)
+        self.assert_posicao_vertical(1, 2.0, passaro_amarelo)
+        self.assert_posicao_vertical(1, 2.01, passaro_amarelo)
+        self.assert_posicao_vertical(2, 2.02, passaro_amarelo)
+        self.assert_posicao_vertical(2, 2.03, passaro_amarelo)
+        self.assert_posicao_vertical(2, 2.04, passaro_amarelo)
+        self.assert_posicao_vertical(2, 2.05, passaro_amarelo)
 
         # descendo
 
-        assert_vertical(46, 5.26)
-        assert_vertical(46, 5.27)
-        assert_vertical(46, 5.279999999999999)
-        assert_vertical(46, 5.29)
-        assert_vertical(46, 5.3)
-        assert_vertical(46, 5.3100000000000005)
-        assert_vertical(45, 5.32)
-        assert_vertical(45, 5.33)
-        assert_vertical(45, 5.34)
-        assert_vertical(45, 5.35)
-        assert_vertical(45, 5.359999999999999)
-        assert_vertical(45, 5.37)
-        assert_vertical(45, 5.38)
-        assert_vertical(45, 5.390000000000001)
-        assert_vertical(45, 5.4)
-        assert_vertical(45, 5.41)
-        assert_vertical(45, 5.42)
-        assert_vertical(45, 5.43)
-        assert_vertical(45, 5.4399999999999995)
-        assert_vertical(45, 5.45)
-        assert_vertical(45, 5.46)
-        assert_vertical(45, 5.470000000000001)
-        assert_vertical(45, 5.48)
+        self.assert_posicao_vertical(46, 5.26, passaro_amarelo)
+        self.assert_posicao_vertical(46, 5.27, passaro_amarelo)
+        self.assert_posicao_vertical(46, 5.279999999999999, passaro_amarelo)
+        self.assert_posicao_vertical(46, 5.29, passaro_amarelo)
+        self.assert_posicao_vertical(46, 5.3, passaro_amarelo)
+        self.assert_posicao_vertical(46, 5.3100000000000005, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.32, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.33, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.34, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.35, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.359999999999999, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.37, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.38, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.390000000000001, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.4, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.41, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.42, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.43, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.4399999999999995, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.45, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.46, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.470000000000001, passaro_amarelo)
+        self.assert_posicao_vertical(45, 5.48, passaro_amarelo)
 
         # preparando para impacto no chão
-        assert_vertical(1, 8.0)
-        assert_vertical(1, 8.01)
+        self.assert_posicao_vertical(1, 8.0, passaro_amarelo)
+        self.assert_posicao_vertical(1, 8.01, passaro_amarelo)
 
         # colisão
-        assert_vertical(0, 8.04)
+        self.assert_posicao_vertical(0, 8.04, passaro_amarelo)
         passaro_amarelo.colidir_com_chao()
         self.assertEqual(DESTRUIDO, passaro_amarelo.status)
 
@@ -681,3 +736,10 @@ def test_lancamento_45_graus(self):
         # t = 2 + (delta_t / 100)
         # x, y = passaro_amarelo.calcular_posicao(t)
         # print('        self.assert_passaro_posicao(%s, %s, ATIVO, passaro_amarelo, %s)' % (x, y, t))
+
+    def assert_posicao_vertical(self, y, tempo, passaro):
+        """
+         Método auxiliar que mantém x fixo com valor 1, status Ativo, variando apenas o tempo e a posição y
+         Atenção, esse não é um teste porque não começa com prefixo "test"
+         """
+        self.assert_passaro_posicao(1, y, ATIVO, passaro, tempo)
