docs: Improve Portuguese documentation and comments for clarity and consistency.

rubensdemelo · rubensdemelo · commit faae206c82ee · 2026-03-02T15:53:41.000+02:00
diff --git a/lib/src/formatters/cep_input_formatter.dart b/lib/src/formatters/cep_input_formatter.dart
@@ -1,6 +1,6 @@
 import 'package:flutter/services.dart';
 
-/// Formata o valor do campo com a mascara de CEP `XX.XXX-XXX`
+/// Formata o valor do campo com a máscara de CEP `XX.XXX-XXX`.
 ///
 /// `ponto` indica se o formato do CEP deve utilizar `.` ou não.
 class CepInputFormatter extends TextInputFormatter {
diff --git a/lib/src/formatters/cert_nascimento_input_formatter.dart b/lib/src/formatters/cert_nascimento_input_formatter.dart
@@ -1,6 +1,6 @@
 import 'package:flutter/services.dart';
 
-/// Formata o valor do campo com a mascara de Certidão de Nascimento: `XXXXXX XX XX XXXX X XXXXX XXX XXXXXXX XX`
+/// Formata o valor do campo com a máscara de Certidão de Nascimento: `XXXXXX XX XX XXXX X XXXXX XXX XXXXXXX XX`.
 class CertNascimentoInputFormatter extends TextInputFormatter {
   @override
   TextEditingValue formatEditUpdate(
diff --git a/lib/src/formatters/cnpj_alfanumerico_input_formatter.dart b/lib/src/formatters/cnpj_alfanumerico_input_formatter.dart
@@ -1,7 +1,7 @@
 import 'package:brasil_fields/src/interfaces/compoundable_formatter.dart';
 import 'package:flutter/services.dart';
 
-/// Formata o valor do campo com a mascara de CNPJ `XX.XXX.XXX/XXXX-XX`
+/// Formata o valor do campo com a máscara de CNPJ `XX.XXX.XXX/XXXX-XX`.
 ///
 /// Deve ser usado num TextInput que recebe letras e números:
 /// ```dart
diff --git a/lib/src/formatters/cnpj_input_formatter.dart b/lib/src/formatters/cnpj_input_formatter.dart
@@ -1,7 +1,7 @@
 import 'package:brasil_fields/src/interfaces/compoundable_formatter.dart';
 import 'package:flutter/services.dart';
 
-/// Formata o valor do campo com a mascara de CNPJ `99.999.999/9999-99`
+/// Formata o valor do campo com a máscara de CNPJ `99.999.999/9999-99`.
 class CnpjInputFormatter extends TextInputFormatter
     implements CompoundableFormatter {
   // Define o tamanho máximo do campo.
diff --git a/lib/src/formatters/cns_formatter.dart b/lib/src/formatters/cns_formatter.dart
@@ -5,7 +5,7 @@ class CNSInputFormatter extends TextInputFormatter {
   @override
   TextEditingValue formatEditUpdate(
       TextEditingValue oldValue, TextEditingValue newValue) {
-    // verifica o tamanho máximo do campo.
+    // verifica o tamanho máximo do campo
     if (newValue.text.length > 15) return oldValue;
 
     var posicaoCursor = newValue.selection.end;
diff --git a/lib/src/formatters/compound_formatters/compound_formatter.dart b/lib/src/formatters/compound_formatters/compound_formatter.dart
@@ -1,11 +1,11 @@
 import 'package:brasil_fields/src/interfaces/compoundable_formatter.dart';
 import 'package:flutter/services.dart';
 
-/// Combina dois ous mais instâncias de [Formatter] de forma que
-/// seja possível interpolar de um para outro
+/// Combina dois ou mais instâncias de [Formatter] de forma que
+/// seja possível interpolar de um para outro.
 class CompoundFormatter extends TextInputFormatter {
   /// Guarda uma lista de [CompoundableFormatter] que são encadeados
-  /// na mesma ordem em que estão posicionados na lista
+  /// na mesma ordem em que estão posicionados na lista.
   final List<CompoundableFormatter> _formatters;
 
   CompoundFormatter(this._formatters)
diff --git a/lib/src/formatters/cpf_input_formatter.dart b/lib/src/formatters/cpf_input_formatter.dart
@@ -1,7 +1,7 @@
 import 'package:brasil_fields/src/interfaces/compoundable_formatter.dart';
 import 'package:flutter/services.dart';
 
-/// Formata o valor do campo com a mascara de CPF: `XXX.XXX.XXX-XX`
+/// Formata o valor do campo com a máscara de CPF: `XXX.XXX.XXX-XX`.
 class CpfInputFormatter extends TextInputFormatter
     implements CompoundableFormatter {
   // Define o tamanho máximo do campo.
diff --git a/lib/src/formatters/data_input_formatter.dart b/lib/src/formatters/data_input_formatter.dart
@@ -1,6 +1,6 @@
 import 'package:flutter/services.dart';
 
-/// Formata o valor do campo com a mascara de data `01/01/1900`.
+/// Formata o valor do campo com a máscara de data `01/01/1900`.
 class DataInputFormatter extends TextInputFormatter {
   @override
   TextEditingValue formatEditUpdate(
diff --git a/lib/src/formatters/hora_input_formatter.dart b/lib/src/formatters/hora_input_formatter.dart
@@ -1,8 +1,8 @@
 import 'package:flutter/services.dart';
 
-/// Formata o valor do campo com a máscara de hora `HH:mm`
+/// Formata o valor do campo com a máscara de hora `HH:mm`.
 ///
-/// Nao aceita [hora > 24] e [minuto > 59]
+/// Não aceita [hora > 24] e [minuto > 59].
 class HoraInputFormatter extends TextInputFormatter {
   @override
   TextEditingValue formatEditUpdate(
diff --git a/lib/src/formatters/iof_input_formatter.dart b/lib/src/formatters/iof_input_formatter.dart
@@ -1,6 +1,6 @@
 import 'package:flutter/services.dart';
 
-/// Formata o valor do campo com a máscara `1,234567`
+/// Formata o valor do campo com a máscara `1,234567`.
 class IOFInputFormatter extends TextInputFormatter {
   @override
   TextEditingValue formatEditUpdate(
diff --git a/lib/src/formatters/ncm_input_formatter.dart b/lib/src/formatters/ncm_input_formatter.dart
@@ -1,6 +1,6 @@
 import 'package:flutter/services.dart';
 
-/// Formata o valor do campo com a máscara de NCM: `XXXX.XX.XX`
+/// Formata o valor do campo com a máscara de NCM: `XXXX.XX.XX`.
 class NCMInputFormatter extends TextInputFormatter {
   @override
   TextEditingValue formatEditUpdate(
diff --git a/lib/src/formatters/nup_input_formatter.dart b/lib/src/formatters/nup_input_formatter.dart
@@ -1,7 +1,7 @@
 import 'package:flutter/services.dart';
 
-/// Formata o valor do campo com a máscara de NUP (Numeração Única de Processos): `XXXXXXX-XX.XXXX.X.XX.XXXX`
-/// Referência: [Documentação CNJ](https://www.cnj.jus.br/programas-e-acoes/numeracao-unica/)
+/// Formata o valor do campo com a máscara de NUP (Numeração Única de Processos): `XXXXXXX-XX.XXXX.X.XX.XXXX`.
+/// Referência: [Documentação CNJ](https://www.cnj.jus.br/programas-e-acoes/numeracao-unica/).
 class NUPInputFormatter extends TextInputFormatter {
   @override
   TextEditingValue formatEditUpdate(
diff --git a/lib/src/formatters/peso_input_formatter.dart b/lib/src/formatters/peso_input_formatter.dart
@@ -1,6 +1,6 @@
 import 'package:flutter/services.dart';
 
-/// Formata o valor do campo com a mascara kg,g (ex: `103,8`)
+/// Formata o valor do campo com a máscara kg,g (ex: `103,8`).
 class PesoInputFormatter extends TextInputFormatter {
   @override
   TextEditingValue formatEditUpdate(
diff --git a/lib/src/formatters/placa_veiculo_formatter.dart b/lib/src/formatters/placa_veiculo_formatter.dart
@@ -2,16 +2,15 @@ import 'package:flutter/services.dart';
 
 /// Formata o valor do campo com a máscara de veículos `XXX-XXXX`.
 ///
-///Não se deve utilizar o `FilteringTextInputFormatter.digitsOnly` com
-///este formatter.
+/// Não se deve utilizar o `FilteringTextInputFormatter.digitsOnly` com
+/// este formatter.
 class PlacaVeiculoInputFormatter extends TextInputFormatter {
   @override
   TextEditingValue formatEditUpdate(
     TextEditingValue oldValue,
     TextEditingValue newValue,
   ) {
-    // verifica o tamanho máximo do campo
-    // Verifica o tamanho máximo do campo (7 caracteres alfanuméricos + 1 traço).
+    // verifica o tamanho máximo do campo (7 caracteres alfanuméricos + 1 traço)
     if (newValue.text.replaceAll('-', '').length > 7) return oldValue;
 
     var selectionIndex = newValue.selection.end;
diff --git a/lib/src/formatters/real_input_formatter.dart b/lib/src/formatters/real_input_formatter.dart
@@ -3,7 +3,6 @@ import 'package:flutter/services.dart';
 import 'adiciona_separador.dart';
 
 /// Formata o valor do campo com a máscara `999.999.999.999`.
-
 class RealInputFormatter extends TextInputFormatter {
   RealInputFormatter({this.moeda = false});
 
diff --git a/lib/src/formatters/telefone_input_formatter.dart b/lib/src/formatters/telefone_input_formatter.dart
@@ -7,7 +7,7 @@ class TelefoneInputFormatter extends TextInputFormatter {
   @override
   TextEditingValue formatEditUpdate(
       TextEditingValue oldValue, TextEditingValue newValue) {
-    // Verifica o tamanho máximo do campo.
+    // verifica o tamanho máximo do campo
     if (newValue.text.length > 11) return oldValue;
 
     final newValueLength = newValue.text.length;
diff --git a/lib/src/formatters/temperatura_input_formatter.dart b/lib/src/formatters/temperatura_input_formatter.dart
@@ -1,6 +1,6 @@
 import 'package:flutter/services.dart';
 
-/// Formata o valor do campo com a mascara °C (ex: `10,8`).
+/// Formata o valor do campo com a máscara °C (ex: `10,8`).
 class TemperaturaInputFormatter extends TextInputFormatter {
   @override
   TextEditingValue formatEditUpdate(
diff --git a/lib/src/formatters/validade_cartao_input_formatter.dart b/lib/src/formatters/validade_cartao_input_formatter.dart
@@ -4,7 +4,7 @@ import 'package:flutter/services.dart';
 ///
 ///  `maxLength = 4` MM/AA (default)
 ///
-/// `maxLength = 6` MM/AAAAA.
+/// `maxLength = 6` MM/AAAA.
 class ValidadeCartaoInputFormatter extends TextInputFormatter {
   final int maxLength;
 
diff --git a/lib/src/interfaces/compoundable_formatter.dart b/lib/src/interfaces/compoundable_formatter.dart
@@ -1,9 +1,9 @@
 import 'package:flutter/services.dart';
 
 /// Define um [TextInputFormatter] que pode ser combinado com outros
-/// para que seja possível interpolar de um para outro
-/// Usado em [CompoundableFormatter]
+/// para que seja possível interpolar de um para outro.
+/// Usado em [CompoundFormatter].
 abstract class CompoundableFormatter extends TextInputFormatter {
-  /// Tamanho máximo do Formatter
+  /// Tamanho máximo do Formatter.
   int get maxLength;
 }
diff --git a/lib/src/util/util_brasil_fields.dart b/lib/src/util/util_brasil_fields.dart
@@ -93,6 +93,7 @@ class UtilBrasilFields {
     }
   }
 
+  /// Retorna o DDD do telefone informado.
   static String obterDDD(String telefone) {
     if (telefone.length != 14 && telefone.length != 15) {
       throw ArgumentError.value(
@@ -105,7 +106,7 @@ class UtilBrasilFields {
     return telefone.substring(1, 3);
   }
 
-  ///Faz a validação do CPF retornando `[true]` ou `[false]`
+  /// Faz a validação do CPF retornando `[true]` ou `[false]`.
   static bool isCPFValido(String? cpf) => CPFValidator.isValid(cpf);
 
   /// Faz a validação do CNPJ retornando `[true]` ou `[false]`
@@ -118,7 +119,7 @@ class UtilBrasilFields {
           ? CnpjAlfanumericoValidator.isValid(cnpj)
           : CNPJValidator.isValid(cnpj);
 
-  ///Faz a validação do NUP retornando `[true]` ou `[false]`
+  /// Faz a validação do NUP retornando `[true]` ou `[false]`.
   static bool isNUPValido(String? nup) => NUPValidator.isValid(nup);
 
   /// Gera um CPF aleatório
diff --git a/lib/src/util/util_data.dart b/lib/src/util/util_data.dart
@@ -73,10 +73,10 @@ class UtilData {
       if (dataInt != null) {
         return dataInt;
       } else {
-        throw Exception('Nao foi possível obter o mes da data $data');
+        throw Exception('Não foi possível obter o mes da data $data');
       }
     } else {
-      throw Exception('Nao foi possível obter o mes da data $data');
+      throw Exception('Não foi possível obter o mes da data $data');
     }
   }
 
@@ -93,10 +93,10 @@ class UtilData {
       if (dataInt != null) {
         return dataInt;
       } else {
-        throw Exception('Nao foi possível obter o dia da data $data');
+        throw Exception('Não foi possível obter o dia da data $data');
       }
     } else {
-      throw Exception('Nao foi possível obter o dia da data $data');
+      throw Exception('Não foi possível obter o dia da data $data');
     }
   }
 
diff --git a/lib/src/validators/cnpj_alfanumerico_validator.dart b/lib/src/validators/cnpj_alfanumerico_validator.dart
@@ -24,8 +24,8 @@ class CnpjAlfanumericoValidator {
 
   static const stipRegex = r'[^A-Z\d]';
 
-  /// Compute the Verifier Digit (or 'Dígito Verificador (DV)' in PT-BR).
-  /// You can learn more about the algorithm on [wikipedia (pt-br)](https://pt.wikipedia.org/wiki/D%C3%ADgito_verificador)
+  // calcula o Dígito Verificador (DV)
+  // mais informações em [wikipedia (pt-br)](https://pt.wikipedia.org/wiki/D%C3%ADgito_verificador)
   static int _verifierDigit(String cnpj) {
     var index = 2;
 
@@ -67,17 +67,17 @@ class CnpjAlfanumericoValidator {
       cnpj = strip(cnpj);
     }
 
-    // cnpj must be defined
+    // cnpj deve ser informado
     if (cnpj == null || cnpj.isEmpty) {
       return false;
     }
 
-    // cnpj must have 14 chars
+    // cnpj deve ter 14 caracteres
     if (cnpj.length != 14) {
       return false;
     }
 
-    // cnpj can't be blacklisted
+    // cnpj não pode estar na lista de bloqueio
     if (blockList.contains(cnpj)) {
       return false;
     }
diff --git a/lib/src/validators/cnpj_validator.dart b/lib/src/validators/cnpj_validator.dart
@@ -19,8 +19,8 @@ class CNPJValidator {
 
   static const stipRegex = r'[^\d]';
 
-  // Compute the Verifier Digit (or 'Dígito Verificador (DV)' in PT-BR).
-  // You can learn more about the algorithm on [wikipedia (pt-br)](https://pt.wikipedia.org/wiki/D%C3%ADgito_verificador)
+  // calcula o Dígito Verificador (DV)
+  // mais informações em [wikipedia (pt-br)](https://pt.wikipedia.org/wiki/D%C3%ADgito_verificador)
   static int _verifierDigit(String cnpj) {
     var index = 2;
 
@@ -59,17 +59,17 @@ class CNPJValidator {
       cnpj = strip(cnpj);
     }
 
-    // cnpj must be defined
+    // cnpj deve ser informado
     if (cnpj == null || cnpj.isEmpty) {
       return false;
     }
 
-    // cnpj must have 14 chars
+    // cnpj deve ter 14 caracteres
     if (cnpj.length != 14) {
       return false;
     }
 
-    // cnpj can't be blacklisted
+    // cnpj não pode estar na lista de bloqueio
     if (blockList.contains(cnpj)) {
       return false;
     }
diff --git a/lib/src/validators/cpf_validator.dart b/lib/src/validators/cpf_validator.dart
@@ -20,8 +20,8 @@ class CPFValidator {
 
   static const stipRegex = r'[^\d]';
 
-  // Compute the Verifier Digit (or 'Dígito Verificador (DV)' in PT-BR).
-  // You can learn more about the algorithm on [wikipedia (pt-br)](https://pt.wikipedia.org/wiki/D%C3%ADgito_verificador)
+  // calcula o Dígito Verificador (DV)
+  // mais informações em [wikipedia (pt-br)](https://pt.wikipedia.org/wiki/D%C3%ADgito_verificador)
   static int _verifierDigit(String cpf) {
     final numbers =
         cpf.split('').map((number) => int.parse(number, radix: 10)).toList();
@@ -59,17 +59,17 @@ class CPFValidator {
       cpf = strip(cpf);
     }
 
-    // CPF must be defined
+    // CPF deve ser informado
     if (cpf == null || cpf.isEmpty) {
       return false;
     }
 
-    // CPF must have 11 chars
+    // CPF deve ter 11 caracteres
     if (cpf.length != 11) {
       return false;
     }
 
-    // CPF can't be blacklisted
+    // CPF não pode estar na lista de bloqueio
     if (blockList.contains(cpf)) {
       return false;
     }
diff --git a/lib/src/validators/nup_validator.dart b/lib/src/validators/nup_validator.dart
@@ -25,8 +25,8 @@ class NUPValidator {
     return nup.replaceAll(regex, '');
   }
 
-  // Compute the Check Digit (or 'Dígito Verificador (DV)' in PT-BR).
-  // You can learn more about the algorithm on [CNJ (pt-br)](https://atos.cnj.jus.br/files/compilado23285720221017634de539229ab.pdf)
+  // calcula o Dígito Verificador (DV)
+  // mais informações em [CNJ (pt-br)](https://atos.cnj.jus.br/files/compilado23285720221017634de539229ab.pdf)
   static String _checkDigit(String nup) {
     final sequential = nup.substring(0, 7);
     final year = nup.substring(9, 13);
diff --git a/test/util_brasil_fields_test.dart b/test/util_brasil_fields_test.dart
@@ -228,14 +228,14 @@ void main() {
   });
 
   test('Obter CPF', () {
-    ///Gerado por https://www.4devs.com.br/gerador_de_cpf
+    // gerado por https://www.4devs.com.br/gerador_de_cpf
     const cpfSemMascara = '48620265083';
     const cpfComMascara = '486.202.650-83';
     expect(UtilBrasilFields.obterCpf(cpfSemMascara), cpfComMascara);
   });
 
   test('Obter CNPJ', () {
-    ///Gerado por https://www.4devs.com.br/gerador_de_cnpj
+    // gerado por https://www.4devs.com.br/gerador_de_cnpj
     const cpnjSemMascara = '77343168000124';
     const cpnjComMascara = '77.343.168/0001-24';
     expect(UtilBrasilFields.obterCnpj(cpnjSemMascara), cpnjComMascara);
