Permalink
Browse files

YARDOC

  • Loading branch information...
1 parent 5fe1c3f commit 0d5cd22e66fd5f274f4639304b36e85a1ee901b2 @weppos committed Dec 7, 2010
View
@@ -126,7 +126,7 @@ def self.deprecate(message = nil)
warn("DEPRECATION WARNING: #{message}")
end
- # Appends "Please report issue to" to the message
+ # Appends <em>Please report issue to</em> to the message
# and raises a new +error+ with the final message.
#
# @param [Exception] error
View
@@ -49,15 +49,15 @@ def to_s
# Returns a human-readable representation of this answer.
#
- # @return [String] The result of #inspect on content.
+ # @return [String] The result of {#inspect} on content.
def inspect
content.inspect
end
- # Invokes <tt>match</tt> on answer <tt>@content</tt>
+ # Invokes {#match} on answer {#content}
# and returns the match as <tt>MatchData</tt> or <tt>nil</tt>.
#
- # @param [RegExp, String] match
+ # @param [Regexp, String] match
# @return [MatchData] If pattern matches #content
# @return [nil] If pattern doesn't match #content
#
@@ -67,10 +67,10 @@ def match(pattern)
content.match(pattern)
end
- # Invokes <tt>match</tt> and returns <tt>true</tt> if <tt>pattern</tt>
- # matches <tt>@content</tt>, <tt>false</tt> otherwise.
+ # Invokes {#match} and returns <tt>true</tt> if <tt>pattern</tt>
+ # matches {#content}, <tt>false</tt> otherwise.
#
- # @param [RegExp, String] match
+ # @param [Regexp, String] match
# @return [Boolean]
#
# @see #match
@@ -125,7 +125,7 @@ def parser
# Returns a Hash containing all supported properties for this answer
# along with corresponding values.
#
- # @return [Hash]
+ # @return [{ Symbol => Object }]
def properties
hash = {}
Parser::PROPERTIES.each { |property| hash[property] = send(property) }
@@ -134,9 +134,8 @@ def properties
# Returns <tt>true</tt> if the <tt>property</tt> passed as symbol
# is supported by any available parser for this answer.
- # See also <tt>Whois::Answer::Parser.supported?</tt>.
#
- # @param [Symbol] property - The name of the property to check.
+ # @param [Symbol] property The name of the property to check.
# @return [Boolean]
#
# @see Whois::Answer::Parser#property_supported?
@@ -146,9 +145,9 @@ def property_supported?(property)
end
- # Checks whether this Answer is different than +other+.
+ # Checks whether this {Answer} is different than +other+.
#
- # Comparing the Answer content is not as trivial as you may think.
+ # Comparing the {Answer} content is not as trivial as you may think.
# WHOIS servers can inject into the WHOIS response strings that changes at every request,
# such as the timestamp the request was generated or the number of requests left
# for your current IP.
@@ -186,9 +185,9 @@ def unchanged?(other)
# Collects and returns all the contacts.
#
- # @return [Array<Whois::Aswer::Contact>]
+ # @return [Array<Whois::Answer::Contact>]
#
- # @see Whois::Answer::Parser#contacts?
+ # @see Whois::Answer::Parser#contacts
#
def contacts
parser.contacts
@@ -21,11 +21,11 @@ module Whois
class Answer
#
- # = Contacts
+ # = Contact
#
- # Holds the details of a <tt>Contact</tt> extracted from the WHOIS <tt>Answer</tt>.
+ # Holds the details of a {Whois::Answer::Contact} extracted from the WHOIS response.
#
- # A <tt>Contact</tt> is composed by the following attributes:
+ # A contact is composed by the following attributes:
#
# * <tt>:id</tt>:
# * <tt>:type</tt>: the contact type (1 = registrant, 2 = admin, 3 = technical).
@@ -23,7 +23,7 @@ class Answer
#
# = Nameserver
#
- # Holds the details of the Name Servers extracted from the WHOIS answer.
+ # Holds the details of the Name Servers extracted from the WHOIS response.
#
# A Nameserver is composed by the following attributes:
#
@@ -39,23 +39,35 @@ class Parser
:nameservers,
]
+ # @return [Whois::Answer] The answer referenced by this parser.
attr_reader :answer
+ # Initializes and return a new parser from +answer+.
+ #
+ # @param [Whois::Answer]
+ #
def initialize(answer)
@answer = answer
end
# Returns an array with all host-specific parsers initialized for the parts
# contained into this parser.
# The array is lazy-initialized.
+ #
+ # @return [Array<Whois::Answer::Parser::Base>]
+ #
def parsers
@parsers ||= init_parsers
end
# Returns <tt>true</tt> if the <tt>property</tt> passed as symbol
# is supported by any available parser.
- # See also <tt>Whois::Answer::Parser::Base.supported?</tt>.
+ #
+ # @return [Boolean]
+ #
+ # @see Whois::Answer::Parser::Base.property_supported?
+ #
def property_supported?(property)
parsers.any? { |parser| parser.property_supported?(property) }
end
@@ -94,10 +106,10 @@ def unchanged?(other)
# Collects and returns all the contacts from all the answer parts.
#
- # @return [Array<Whois::Aswer::Contact>]
+ # @return [Array<Whois::Answer::Contact>]
#
- # @see Whois::Answer#contacts?
- # @see Whois::Answer::Parser::Base#contacts?
+ # @see Whois::Answer#contacts
+ # @see Whois::Answer::Parser::Base#contacts
#
def contacts
parsers.inject([]) { |all, parser| all.concat(parser.contacts) }
@@ -155,42 +167,37 @@ def delegate_to_parsers(method, *args, &block)
# and returns the final array of server-specific parsers.
#
# Parsers are initialized in reverse order for performance reason.
- # See also <tt>#select_parser</tt>.
#
- # ==== Returns
+ # @return [Array<Class>] An array of Class,
+ # where each item is the parts reverse-N specific parser {Class}.
+ # Each {Class} is expected to be a child of {Whois::Answer::Parser::Base}.
#
- # Returns an Array of Class,
- # where each item is the parts reverse-N specific parser Class.
- # Each Class is expected to be a child of Whois::Answer::Parser::Base.
- #
- # ==== Examples
+ # @example
#
# parser.parts
# # => [whois.foo.com, whois.bar.com]
#
# parser.parsers
# # => [Whois::Answer::Parser::WhoisBarCom, Whois::Answer::Parser::WhoisFooCom]
#
+ # @see Whois::Answer::Parser#select_parser
+ #
def init_parsers
answer.parts.reverse.map { |part| self.class.parser_for(part) }
end
- # Selects the first parser in <tt>#parsers</tt>
- # where <tt>given</tt> matches <tt>status</tt>.
+ # Selects the first parser in {#parsers}
+ # where given property matches <tt>status</tt>.
#
- # ==== Parameters
+ # @param [Symbol] property The property to search for.
+ # @param [Symbol] status The status value.
#
- # property:: The Symbol property to search for.
- # status:: The Symbol status (default: :any).
+ # @return [Whois::Answer::Parser::Base]
+ # The parser which satisfies given requirement.
+ # @return [nil]
+ # If the parser wasn't found.
#
- # ==== Returns
- #
- # Whois::Answer::Parser::Base::
- # The parser which satisfies given requirement.
- # nil::
- # If the parser wasn't found.
- #
- # ==== Examples
+ # @example
#
# select_parser(:nameservers)
# # => #<Whois::Answer::Parser::WhoisExampleCom>
@@ -221,24 +228,21 @@ def all_with_args?(*args, &block)
# The parser class is selected according to the
# value of the <tt>#host</tt> attribute for given <tt>part</tt>.
#
- # ==== Parameters
- #
- # part:: The Whois::Answer::Parser::Part to get the parser for.
+ # @param [Whois::Answer::Part] part The part to get the parser for.
#
- # ==== Returns
- #
- # Returns an instance of the specific parser for given part.
- # The instance is expected to be a child of Whois::Answer::Parser::Base.
+ # @return [Whois::Answer::Parser::Base]
+ # An instance of the specific parser for given part.
+ # The instance is expected to be a child of {Whois::Answer::Parser::Base}.
#
- # ==== Examples
+ # @example
#
# # Parser for a known host
# Parser.parser_for("whois.example.com")
- # #<Whois::Answer::Parser::WhoisExampleCom>
+ # # => #<Whois::Answer::Parser::WhoisExampleCom>
#
# # Parser for an unknown host
# Parser.parser_for("missing.example.com")
- # #<Whois::Answer::Parser::Blank>
+ # # => #<Whois::Answer::Parser::Blank>
#
def self.parser_for(part)
parser_klass(part.host).new(part)
@@ -251,19 +255,15 @@ def self.parser_for(part)
# a custom parser, simple make sure the class is loaded in the Ruby
# environment before this method is called.
#
- # ==== Parameters
- #
- # host:: A String with the host.
+ # @param [String] host The server host.
#
- # ==== Returns
+ # @return [Class] The instance of Class representing the parser Class
+ # corresponding to <tt>host</tt>. If <tt>host</tt> doesn't have
+ # a specific parser implementation, then returns
+ # the {Whois::Answer::Parser::Blank} {Class}.
+ # The {Class} is expected to be a child of {Whois::Answer::Parser::Base}.
#
- # Returns an instance of Class representing the parser Class
- # corresponding to <tt>host</tt>.
- # If <tt>host</tt> doesn't have a specific parser implementation,
- # then returns the Whois::Answer::Parser::Blank Class.
- # The Class is expected to be a child of Whois::Answer::Parser::Base.
- #
- # ==== Examples
+ # @example
#
# Parser.parser_klass("missing.example.com")
# # => Whois::Answer::Parser::Blank
@@ -287,19 +287,17 @@ def self.parser_klass(host)
# Converts <tt>host</tt> to the corresponding parser class name.
#
- # ==== Parameters
- #
- # host:: A String with the host.
+ # @param [String] host The server host.
+ # @return [String] The class name.
#
- # ==== Examples
+ # @example
#
# Parser.host_to_parser("whois.nic.it")
# # => "WhoisNicIt"
#
# Parser.host_to_parser("whois.nic-info.it")
# # => "WhoisNicInfoIt"
#
- # Returns a String with the class name.
def self.host_to_parser(host)
host.to_s.
gsub(/[.-]/, '_').
@@ -308,13 +306,9 @@ def self.host_to_parser(host)
# Requires the file at <tt>whois/answer/parser/#{name}</tt>.
#
- # ==== Parameters
- #
- # name:: A string with the file name.
- #
- # ==== Returns
+ # @param [String] name The file name to load.
#
- # Nothing.
+ # @return [void]
#
def self.autoload(name)
file = "whois/answer/parser/#{name}"
@@ -265,7 +265,7 @@ def unchanged?(other)
# Collects and returns all the available contacts.
#
- # @return [Array<Whois::Aswer::Contact>]
+ # @return [Array<Whois::Answer::Contact>]
#
# @see Whois::Answer#contacts
# @see Whois::Answer::Parser#contacts
@@ -281,10 +281,10 @@ def contacts
# Checks whether this is a throttle response.
# The default implementation always returns +false+.
#
- # @abstract This method returns false by default.
- #
# @return [false]
#
+ # @abstract This method returns false by default.
+ #
# @see Whois::Answer#throttle?
# @see Whois::Answer::Parser#throttle?
#
@@ -23,12 +23,12 @@ class Answer
#
# = Part
#
- # A single <tt>Whois::Answer</tt> fragment. For instance,
- # in case of thin server, a <tt>Whois::Answer</tt> may be composed by
+ # A single {Whois::Answer} fragment. For instance,
+ # in case of thin server, a {Whois::Answer} can be composed by
# one or more parts corresponding to all responses
# returned by the WHOIS servers.
#
- # A <tt>Part</tt> is composed by the following attributes:
+ # A part is composed by the following attributes:
#
# * body - The body containing the whois output.
# * host - The host which returned the body.
@@ -23,7 +23,7 @@ class Answer
#
# = Registrar
#
- # Holds the details of the Registrar extracted from the WHOIS answer.
+ # Holds the details of the Registrar extracted from the WHOIS response.
#
# A Registrar is composed by the following attributes:
#
Oops, something went wrong.

0 comments on commit 0d5cd22

Please sign in to comment.