Permalink
Browse files

YARD'ed up the documentation.

  • Loading branch information...
1 parent bdabedf commit 3b4c64b6939f93659f66435e8d544a70f963c168 Daz Oakley committed Feb 16, 2011
Showing with 68 additions and 11 deletions.
  1. +21 −1 lib/biomart.rb
  2. +5 −2 lib/biomart/attribute.rb
  3. +6 −0 lib/biomart/database.rb
  4. +25 −6 lib/biomart/dataset.rb
  5. +7 −2 lib/biomart/filter.rb
  6. +4 −0 lib/biomart/server.rb
View
22 lib/biomart.rb
@@ -43,7 +43,27 @@ class ArgumentError < BiomartError; end
# Centralised request function for handling all of the HTTP requests
# to the biomart servers.
- def request( params={} )
+ #
+ # @param [Hash] params Parameters to be passed to the request
+ # @return [String] The response body
+ #
+ # @example
+ # request({
+ # :url => 'http://www.example.com', # the url
+ # :method => 'get', # get/post
+ # :query => 'a string', # when using post, send this as 'query' (i.e. the biomart query xml)
+ # :timeout => 60 # override the default timeout
+ # })
+ #
+ # @raise Biomart::ArgumentError Raised if a params hash is not passed (or it is empty)
+ # @raise Biomart::HTTPError Raised if a HTTP error was encountered
+ # @raise Biomart::FilterError Raised when a filter is not found
+ # @raise Biomart::AttributeError Raised when an attribute is not found
+ # @raise Biomart::DatasetError Raised when a dataset is not found
+ # @raise Biomart::BiomartError Raised for any other unhandled error
+ def request( params )
+ raise ArgumentError if !params.is_a?(Hash) || params.empty?
+
if params[:url] =~ / /
params[:url].gsub!(" ","+")
end
View
7 lib/biomart/attribute.rb
@@ -12,14 +12,17 @@ def initialize(args)
end
# Convenience method to see if this attribute is hidden from
- # the standard MartView interface. Returns true/false.
+ # the standard MartView interface.
+ #
+ # @return [Boolean] true/false
def hidden?
@hidden
end
# Convenience method to see if this attribute would be
# enabled by default in the standard MartView interface.
- # Returns true/false.
+ #
+ # @return [Boolean] true/false
def default?
@default
end
View
6 lib/biomart/database.rb
@@ -20,6 +20,8 @@ def initialize( url, args )
# Returns an array of the dataset names (biomart 'name')
# for this dataset.
+ #
+ # @return [Array] An array of dataset names
def list_datasets
if @datasets.empty?
fetch_datasets
@@ -29,6 +31,8 @@ def list_datasets
# Returns a hash (keyed by the biomart 'name' for the dataset)
# of all of the Biomart::Dataset objects belonging to this server.
+ #
+ # @return [Hash] A hash of Biomart::Dataset objects keyed by 'name'
def datasets
if @datasets.empty?
fetch_datasets
@@ -38,6 +42,8 @@ def datasets
# Returns true / false if this database is visbile in the
# default MartView interface.
+ #
+ # @return [Boolean] true/false
def visible?
@visible
end
View
31 lib/biomart/dataset.rb
@@ -37,6 +37,8 @@ def initialize( url, args )
# Returns a hash (keyed by the biomart 'internal_name' for the filter)
# of all of the Biomart::Filter objects belonging to this dataset.
+ #
+ # @return [Hash] A hash of Biomart::Filter objects keyed by 'internal_name'
def filters
if @filters.empty?
fetch_configuration()
@@ -46,6 +48,8 @@ def filters
# Returns an array of the filter names (biomart 'internal_name')
# for this dataset.
+ #
+ # @return [Array] An array of filters (their 'internal_name's)
def list_filters
if @filters.empty?
fetch_configuration()
@@ -55,6 +59,8 @@ def list_filters
# Returns a hash (keyed by the biomart 'internal_name' for the attribute)
# of all of the Biomart::Attribute objects belonging to this dataset.
+ #
+ # @return [Hash] A hash of Biomart::Attribute objects keyed by 'internal_name'
def attributes
if @attributes.empty?
fetch_configuration()
@@ -64,6 +70,8 @@ def attributes
# Returns an array of the attribute names (biomart 'internal_name')
# for this dataset.
+ #
+ # @return [Array] An array of attributes (their 'internal_name's)
def list_attributes
if @attributes.empty?
fetch_configuration()
@@ -73,13 +81,16 @@ def list_attributes
# Function to perform a Biomart count. Returns an integer value for
# the result of the count query.
- #
- # optional arguments:
+ #
+ # arguments:
#
# {
- # :timeout => integer, # set a timeout length for the request (secs)
- # :filters => {} # hash of key-value pairs (filter => search term)
+ # :timeout => integer, # set a timeout length for the request (secs) - optional
+ # :filters => {} # hash of key-value pairs (filter => search term) - optional
# }
+ #
+ # @param [Hash] args The arguments hash
+ # @raise Biomart::ArgumentError Raised when un-supported arguments are passed
def count( args={} )
if args[:federate]
raise Biomart::ArgumentError, "You cannot federate a count query."
@@ -136,6 +147,10 @@ def count( args={} )
#
# But with the :process_results option will return an array of hashes,
# where each hash represents a row of results (keyed by the attribute name).
+ #
+ # @param [Hash] args The arguments hash
+ # @return [Hash/Array] Will return a hash by default (of unprocessed data), or will return an array of hashes
+ # @raise Biomart::ArgumentError Raised if incorrect arguments are passed
def search( args={} )
if args[:required_attributes] and !args[:required_attributes].is_a?(Array)
raise Biomart::ArgumentError, "The :required_attributes option must be passed as an array."
@@ -154,7 +169,10 @@ def search( args={} )
return result
end
- # Utility function to build the Biomart query XML
+ # Utility function to build the Biomart query XML - used by #count and #search.
+ #
+ # @see #count
+ # @see #search
def generate_xml( args={} )
biomart_xml = ""
xml = Builder::XmlMarkup.new( :target => biomart_xml, :indent => 2 )
@@ -184,7 +202,8 @@ def generate_xml( args={} )
end
# Simple heartbeat function to test that a Biomart server is online.
- # Returns true/false.
+ #
+ # @return [Boolean] true/false
def alive?
server = Biomart::Server.new( @url )
return server.alive?
View
9 lib/biomart/filter.rb
@@ -18,20 +18,25 @@ def initialize(args)
end
# Convenience method to see if this filter is hidden from
- # the standard MartView interface. Returns true/false.
+ # the standard MartView interface.
+ #
+ # @return [Boolean] true/false
def hidden?
@hidden
end
# Convenience method to see if this filter would be
# enabled by default in the standard MartView interface.
- # Returns true/false.
+ #
+ # @return [Boolean] true/false
def default?
@default
end
# Convenience method to see if this filter allows multiple
# values to be passed to it.
+ #
+ # @return [Boolean] true/false
def multiple_values?
@multiple_values
end
View
4 lib/biomart/server.rb
@@ -18,6 +18,8 @@ def initialize( url )
# Returns an array of the database names (biomart 'name')
# for this dataset.
+ #
+ # @return [Array] An array of database names
def list_databases
if @databases.empty?
fetch_databases
@@ -27,6 +29,8 @@ def list_databases
# Returns a hash (keyed by the biomart 'name' for the database)
# of all of the Biomart::Database objects belonging to this server.
+ #
+ # @return [Hash] A hash of Biomart::Database objects keyed by the database name
def databases
if @databases.empty?
fetch_databases

0 comments on commit 3b4c64b

Please sign in to comment.