Permalink
Browse files

melhorando documentação

  • Loading branch information...
1 parent 6b452ea commit c2ce6671e2bf27c14321647daf2abf6e523fe34f @kivanio kivanio committed Sep 14, 2010
View
@@ -16,11 +16,15 @@
require 'active_model'
end
-module Brcobranca
+module Brcobranca
+ # Exception lançada quando algum tipo de boleto soicitado ainda não tiver sido implementado.
class NaoImplementado < NotImplementedError
end
+ # Exception lançada quando os dados informados para o boleto estão inválidos.
+ #
+ # Você pode usar assim na sua aplicação:
# rescue Brcobranca::BoletoInvalido => invalido
# puts invalido.errors
class BoletoInvalido < StandardError
@@ -42,26 +46,34 @@ def initialize(boleto)
#
# Ou colocar em um arquivo na pasta initializer do rails.
class Configuration
- # Somente rghost até o momento
+ # Gerador de arquivo de boleto.
+ # @return [Symbol]
+ # @param [Symbol] (Padrão: :rghost)
attr_accessor :gerador
- # Pode ser pdf, jpg e ps.
+ # Formato do arquivo de boleto a ser gerado.
+ # @return [Symbol]
+ # @param [Symbol] (Padrão: :pdf)
# @see http://wiki.github.com/shairontoledo/rghost/supported-devices-drivers-and-formats Veja mais formatos na documentação do rghost.
attr_accessor :formato
- # Resolução em pixels do arquivo gerado
+ # Resolução em pixels do arquivo gerado.
+ # @return [Integer]
+ # @param [Integer] (Padrão: 150)
attr_accessor :resolucao
- def initialize #:nodoc:
+ def initialize
self.gerador = :rghost
self.formato = :pdf
self.resolucao = 150
end
end
+ # Atribui os valores customizados para as configurações.
def self.configuration
@configuration ||= Configuration.new
end
+ # Bloco para realizar configurações customizadas.
def self.setup
yield(configuration)
end
@@ -66,11 +66,11 @@ class Base
attr_accessor :sacado_documento
# Validações
- validates_presence_of :agencia, :conta_corrente, :numero_documento, :message => "não pode estar em branco."
+ validates_presence_of :agencia, :conta_corrente, :moeda, :especie_documento, :especie, :aceite, :numero_documento, :message => "não pode estar em branco."
validates_numericality_of :convenio, :agencia, :conta_corrente, :numero_documento, :message => "não é um número."
# Nova instancia da classe Base
- # @param [Hash] campos usados na criação do boleto.
+ # @param [Hash] campos
def initialize(campos={})
padrao = {
:moeda => "9", :data_documento => Date.today, :dias_vencimento => 1, :quantidade => 1,
@@ -88,89 +88,99 @@ def initialize(campos={})
template_config
end
- # Responsável por definir a logotipo usada no template genérico,
- # retorna o caminho para o <b>logotipo</b> ou <b>false</b> caso nao consiga encontrar o logotipo.
+ # Logotipo do banco
+ # @return [Path] Caminho para o arquivo de logotipo do banco.
def logotipo
File.join(File.dirname(__FILE__),'..','arquivos','logos',"#{class_name}.jpg")
end
- # Retorna dígito verificador do banco, calculado com modulo11 de 9 para 2
+ # Dígito verificador do banco
+ # @return [Integer] 1 caracteres numéricos.
def banco_dv
self.banco.modulo11_9to2
end
- # Retorna código da agencia formatado com zeros a esquerda.
+ # Código da agencia
+ # @return [String] 4 caracteres numéricos.
def agencia=(valor)
@agencia = valor.to_s.rjust(4,'0') unless valor.nil?
end
- # Retorna dígito verificador da agência, calculado com modulo11 de 9 para 2
+ # Dígito verificador da agência
+ # @return [Integer] 1 caracteres numéricos.
def agencia_dv
self.agencia.modulo11_9to2
end
- # Retorna dígito verificador da conta corrente, calculado com modulo11 de 9 para 2
+ # Dígito verificador da conta corrente
+ # @return [Integer] 1 caracteres numéricos.
def conta_corrente_dv
self.conta_corrente.modulo11_9to2
end
- # Retorna dígito verificador do nosso número, calculado com modulo11 de 9 para 2
+ # Dígito verificador do nosso número
+ # @return [Integer] 1 caracteres numéricos.
def nosso_numero_dv
self.numero_documento.modulo11_9to2
end
- # Campo usado apenas na exibição no boleto
- # Deverá ser sobreescrito para cada banco
+ # @abstract Deverá ser sobreescrito para cada banco.
def nosso_numero_boleto
raise NaoImplementado.new("Sobreescreva este método na classe referente ao banco que você esta criando")
end
- # Campo usado apenas na exibição no boleto
- # Deverá ser sobreescrito para cada banco
+ # @abstract Deverá ser sobreescrito para cada banco.
def agencia_conta_boleto
raise NaoImplementado.new("Sobreescreva este método na classe referente ao banco que você esta criando")
end
- # Retorna o valor total do documento: <b>quantidate * valor</b> ou <b>zero(0)</b> caso não consiga efetuar o cálculo.
+ # Valor total do documento: <b>quantidate * valor</b>
+ # @return [Float]
def valor_documento
self.quantidade.to_f * self.valor.to_f
end
- # Retorna o valor total do documento formatado, sem milhar, centena e com zeros a esquerda
+ # Valor total do documento
+ # @return [String] 10 caracteres numéricos.
def valor_documento_formatado
- self.valor_documento.limpa_valor_moeda.to_s.rjust(10,'0')
+ @valor_documento.limpa_valor_moeda.to_s.rjust(10,'0') unless @valor_documento.nil?
end
- # Retorna data de vencimento baseado na <b>data_documento + dias_vencimento</b> ou <b>false</b> caso não consiga efetuar o cálculo.
+ # Data de vencimento baseado na <b>data_documento + dias_vencimento</b>
+ #
+ # @return [Date]
+ # @raise [ArgumentError] Caso {#data_documento} esteja em branco.
def data_vencimento
raise ArgumentError, "data_documento não pode estar em branco." unless self.data_documento
return self.data_documento unless self.dias_vencimento
(self.data_documento + self.dias_vencimento.to_i)
end
- # Retorna o fator de vencimento calculado com base na data de vencimento
+ # Fator de vencimento calculado com base na data de vencimento do boleto.
+ # @return [String] 4 caracteres numéricos.
def fator_vencimento
self.data_vencimento.fator_vencimento
end
- # Retorna número da conta corrente formatado
+ # Número da conta corrente
+ # @return [String] 7 caracteres numéricos.
def conta_corrente=(valor)
@conta_corrente = valor.to_s.rjust(7,'0') unless valor.nil?
end
# Codigo de barras do boleto
#
- # O codigo de barra para cobrança contém 44 posições dispostas da seguinte forma:
- # Posição Tamanho Conteúdo
- # 01 a 03 3 Identificação do Banco
- # 04 a 04 1 Código da Moeda (Real = 9, Outras=0)
- # 05 a 05 1 Dígito verificador do Código de Barras
- # 06 a 09 4 Fator de Vencimento (Vide Nota)
- # 10 a 19 10 Valor
- # 20 a 44 25 Campo Livre - As posições do campo livre ficam a critério de cada Banco arrecadador.
+ # O codigo de barra para cobrança contém 44 posições dispostas da seguinte forma:<br/>
+ # Posição |Tamanho |Conteúdo<br/>
+ # 01 a 03 | 3 | Identificação do Banco<br/>
+ # 04 a 04 | 1 | Código da Moeda (Real = 9, Outras=0)<br/>
+ # 05 a 05 | 1 | Dígito verificador do Código de Barras<br/>
+ # 06 a 09 | 4 | Fator de Vencimento (Vide Nota)<br/>
+ # 10 a 19 | 10 | Valor<br/>
+ # 20 a 44 | 25 | Campo Livre - As posições do campo livre ficam a critério de cada Banco arrecadador.<br/>
#
- # @raise [ArgumentError] caso o número de dígitos não seja igual a 44.
- # @return [String] código de barras formado por 44 dígitos.
+ # @raise [Brcobranca::BoletoInvalido] Caso as informações fornecidas não sejam suficientes ou sejam inválidas.
+ # @return [String] código de barras formado por 44 caracteres numéricos.
def codigo_barras
raise Brcobranca::BoletoInvalido.new(self) unless self.valid?
codigo = codigo_barras_primeira_parte
@@ -185,29 +195,36 @@ def codigo_barras
end
end
- # Responsável por montar a primeira parte do código de barras, que é a mesma para todos banco.
+ # Monta a primeira parte do código de barras, que é a mesma para todos banco.
+ # @return [String] 18 caracteres numéricos.
def codigo_barras_primeira_parte
"#{self.banco}#{self.moeda}#{self.fator_vencimento}#{self.valor_documento_formatado}"
end
- # Responsável por montar a segunda parte do código de barras, que é específico para cada banco.
- # Este método precisa ser reescrito para cada classe de boleto a ser criada.
- def codigo_barras_segunda_parte #:nodoc:
+ # Monta a segunda parte do código de barras, que é específico para cada banco.
+ #
+ # @abstract Deverá ser sobreescrito para cada banco.
+ def codigo_barras_segunda_parte
raise NaoImplementado.new("Sobreescreva este método na classe referente ao banco que você esta criando")
end
protected
+ # Nome da classe do boleto
+ # @return [String]
def class_name
self.class.to_s.split("::").last.downcase
end
+ # Configura gerador de arquivo de boleto e código de barras.
+ #
+ # @raise [Brcobranca::NaoImplementado] Caso não seja suportado pelo Brcobranca.
def template_config
case Brcobranca.configuration.gerador
when :rghost
extend Brcobranca::Boleto::Template::Rghost
else
- raise "Configure o gerador na opção 'Brcobranca.configuration.gerador' corretamente!!!"
+ raise NaoImplementado.new("Configure o gerador na opção 'Brcobranca.configuration.gerador' corretamente!!!")
end
end
@@ -24,11 +24,20 @@ module Rghost
include RGhost unless self.include?(RGhost)
# Gera o boleto em usando o formato desejado [:pdf, :jpg, :tif, :png, :ps, :laserjet, ... etc]
+ #
+ # @return [Stream]
# @see http://wiki.github.com/shairontoledo/rghost/supported-devices-drivers-and-formats Veja mais formatos na documentação do rghost.
+ # @see Rghost#modelo_generico Recebe os mesmos parâmetros do Rghost#modelo_generico.
def to(formato, options={})
modelo_generico(formato, options)
end
+ # Cria o métodos dinâmicos (to_pdf, to_gif e etc) com todos os fomátos válidos.
+ #
+ # @return [Stream]
+ # @see Rghost#modelo_generico Recebe os mesmos parâmetros do Rghost#modelo_generico.
+ # @example
+ # @boleto.to_pdf #=> boleto gerado no formato pdf
def method_missing(m, *args)
method = m.to_s
if method.start_with?("to_")
@@ -38,12 +47,12 @@ def method_missing(m, *args)
end
end
- # Responsável por setar os valores necessários no template genérico
- # Retorna um stream pronto para gravaçào
- # O tipo do arquivo gerado pode ser modificado incluindo a configuração a baixo dentro da sua aplicação:
- # Brcobranca::Config::OPCOES[:tipo] = 'pdf'
- # Ou pode ser passado como paramentro:
- # :formato => 'pdf'
+ # Retorna um stream pronto para gravaçào em arquivo.
+ #
+ # @return [Stream]
+ # @param [Symbol] formato Tipo de formato que será gerado [:pdf, :jpg, :tif, :png, :ps, :laserjet, ... etc].
+ # @param [Hash] options opção para a criação do boleto.
+ # @option options [String] :resolucao Resolução em pixels.
def modelo_generico(formato, options={})
doc=Document.new :paper => :A4 # 210x297
View
@@ -1,11 +1,12 @@
# -*- encoding: utf-8 -*-
+# @author Kivanio Barbosa
module Brcobranca
- # métodos auxiliares de cálculos
+ # Métodos auxiliares de cálculos
module Calculo
- # Método padrão para cálculo de módulo 10 segundo a BACEN.
+ # Calcula módulo 10 segundo a BACEN.
#
# @return [Integer]
- # @raise [ArgumentError]
+ # @raise [ArgumentError] Caso não seja um número inteiro.
def modulo10
raise ArgumentError, "Número inválido" unless self.is_number?
@@ -21,6 +22,10 @@ def modulo10
valor == 10 ? 0 : valor
end
+ # Calcula módulo 10 do Banespa.
+ #
+ # @return [Integer]
+ # @raise [ArgumentError] Caso não seja um número inteiro.
def modulo_10_banespa
raise ArgumentError, "Número inválido" unless self.is_number?
@@ -35,51 +40,55 @@ def modulo_10_banespa
dv == 10 ? 0 : dv
end
- # Método padrão para cálculo de módulo 11 com multiplicaroes de 9 a 2 segundo a BACEN.
- # Usado no DV do Nosso Numero, Agência e Cedente.
- # Retorna + nil + para todos os parametros que nao forem String
- # Retorna + nil + para String em branco
+ # Calcula módulo 11 com multiplicaroes de 9 a 2 segundo a BACEN.
+ #
+ # @return [Integer]
def modulo11_9to2
total = self.multiplicador([9,8,7,6,5,4,3,2])
return (total % 11 )
end
- # Método padrão para cálculo de módulo 11 com multiplicaroes de 2 a 9 segundo a BACEN.
- # Usado no DV do Código de Barras.
- # Retorna + nil + para todos os parametros que não forem String
- # Retorna + nil + para String em branco
+ # Calcula módulo 11 com multiplicaroes de 2 a 9 segundo a BACEN.
+ #
+ # @return [Integer]
def modulo11_2to9
total = self.multiplicador([2,3,4,5,6,7,8,9])
valor = (11 - (total % 11))
return [0,10,11].include?(valor) ? 1 : valor
end
- # Retorna o dígito verificador de <b>modulo 11(9-2)</b> trocando retorno <b>10 por X</b>.
- # Usado por alguns bancos.
+ # Calcula módulo 11 com multiplicaroes de 9 a 2 trocando retorno <b>10 por X</b>.
+ #
+ # @return [Integer, String] Caso resultado for 10, retorna X.
def modulo11_9to2_10_como_x
valor = self.modulo11_9to2
valor == 10 ? "X" : valor
end
- # Retorna o dígito verificador de <b>modulo 11(9-2)</b> trocando retorno <b>10 por 0</b>.
- # Usado por alguns bancos.
+ # Calcula módulo 11 com multiplicaroes de 9 a 2 trocando retorno <b>10 por 0</b>.
+ #
+ # @return [Integer]
def modulo11_9to2_10_como_zero
valor = self.modulo11_9to2
valor == 10 ? 0 : valor
end
- # Retorna true se a String só conter caracteres numéricos.
+ # Verifica se String só contem caracteres numéricos.
+ #
+ # @return [Boolean]
def is_number?
self.to_s.empty? ? false : (self.to_s =~ (/\D/)).nil?
end
- # Soma números inteiros positivos com 2 dígitos ou mais
- # Retorna <b>0(zero)</b> caso seja impossível.
- # Ex. 1 = 1
- # Ex. 11 = (1+1) = 2
- # Ex. 13 = (1+3) = 4
+ # Soma dígitos de números inteiros positivos com 2 dígitos ou mais.
+ #
+ # @return [Integer]
+ # @example
+ # 1 #=> 1
+ # 11 (1+1) #=> 2
+ # 13 (1+3) #=> 4
def soma_digitos
total = case self.to_i
when (0..9)
@@ -95,9 +104,9 @@ def soma_digitos
# Faz a multiplicação de um número pelos fatores passados como parâmetro.
#
- # @param [Array] fatores
+ # @param [Array]
# @return [Integer]
- # @raise [ArgumentError]
+ # @raise [ArgumentError] Caso não seja um número inteiro.
def multiplicador(fatores, &block)
raise ArgumentError, "Número inválido" unless self.is_number?
Oops, something went wrong.

0 comments on commit c2ce667

Please sign in to comment.