lib/repertoire/media/media.rb in repertoire-0.2.2 vs lib/repertoire/media/media.rb in repertoire-0.2.3

@@ -1,27 +1,42 @@
 require 'repertoire/media/exceptions/unknown_media'
 
 module Repertoire
   module Media
     #
-    # Returns the +Hash+ of all registered Media types.
+    # All registered media types.
     #
+    # @return [Hash]
+    #   The media types.
+    #
     def Media.types
       @@media_types ||= {}
     end
 
     #
-    # Returns +true+ if there is a Media type registered with the matching 
-    # _name_.
+    # Determines if a media type has been registered.
     #
+    # @param [Symbol, String] name
+    #   The name of the media type to check for.
+    #
+    # @return [Boolean]
+    #   Specifies whether there is a Media type registered with the
+    #   matching  name.
+    #
     def Media.supports?(name)
       Media.types.has_key?(name.to_sym)
     end
 
     #
-    # Returns the Media type with the matching _name_.
+    # Finds a media type by name.
     #
+    # @param [Symbol, String] name
+    #   The name of the media type to search for.
+    #
+    # @return [Type]
+    #   The Media type with the matching name.
+    #
     def Media.get(name)
       name = name.to_sym
 
       unless Media.supports?(name)
         raise(UnknownMedia,"media type #{name} is not registered",caller)
@@ -29,35 +44,52 @@
 
       return Media.types[name]
     end
 
     #
-    # Returns the +Hash+ of all registered Media types and their associated
-    # URI schemes.
+    # The media types associated to various URI schemes.
     #
+    # @return [Hash]
+    #   All registered Media types and their associated URI schemes.
+    #
     def Media.schemes
       @@media_schemes ||= {}
     end
 
     #
-    # Returns an +Array+ of all registered URI schemes.
+    # URI schemes associated to media types.
     #
+    # @return [Array]
+    #   All registered URI schemes.
+    #
     def Media.registered_schemes
       Media.schemes.keys
     end
 
     #
-    # Returns +true+ if a Media type was registered for the specified
-    # _scheme_, returns +false+ otherwise.
+    # Determines whether a given URI scheme is supported.
     #
+    # @param [String, Symbol] scheme
+    #   The URI scheme to check for.
+    #
+    # @return [Boolean]
+    #   Specifies whether a Media type was registered for the specified
+    #   scheme.
+    #
     def Media.supports_scheme?(scheme)
       Media.schemes.has_key?(scheme.to_s)
     end
 
     #
-    # Returns the Media type that was registered for the specified _scheme_.
+    # Finds the media type that supports a given URI scheme.
     #
+    # @param [String, Symbol] name
+    #   The URI scheme to search for.
+    #
+    # @return [Type]
+    #   The Media type that was registered for the specified scheme.
+    #
     def Media.supports_scheme(name)
       name = name.to_s
 
       unless Media.supports_scheme?(name)
         raise(UnknownMedia,"media type for scheme #{name.dump} is not registered",caller)
@@ -65,36 +97,55 @@
 
       return Media.schemes[name]
     end
 
     #
-    # Returns the +Hash+ of all registered Media types and their
-    # associated media storage directories.
+    # Media types associated to media storage directories.
     #
+    # @return [Hash]
+    #   All registered Media types and their associated media storage
+    #   directories.
+    #
     def Media.directories
       @@media_directories ||= {}
     end
 
     #
-    # Returns an +Array+ of all registered directories.
+    # Media storage directories associated with media types.
     #
+    # @return [Array]
+    #   All registered media storage directories.
+    #
     def Media.registered_directories
       Media.directories.keys
     end
 
     #
-    # Returns +true+ if a Media type was registered with the specified
-    # _directory_, returns +false+ otherwise.
+    # Determines if the media storage directory is recognized by any
+    # media type.
     #
+    # @param [String, Symbol] name
+    #   The media storage directory to search for.
+    #
+    # @return [Boolean]
+    #   Specifies whether a Media type was registered with the specified
+    #   media storage directory.
+    #
     def Media.recognizes_directory?(name)
       Media.directories.has_key?(name.to_s)
     end
 
     #
-    # Returns the Media type that was registered for the specified
-    # _directory_.
+    # Finds the media type which uses a given media storage directory.
     #
+    # @param [String, Symbol] name
+    #   The media storage directory to search for.
+    #
+    # @return [Type]
+    #   The Media type that was registered for the specified media storage
+    #   directory.
+    #
     def Media.recognizes_directory(name)
       name = name.to_s
 
       unless Media.recognizes_directory?(name)
         raise(UnknownMedia,"media type for directory #{name.dump} is not registered",caller)
@@ -102,18 +153,30 @@
 
       return Media.directories[name]
     end
 
     #
-    # Get the Media type that was registered for the scheme of the
-    # specified _uri_.
+    # Get the Media type that was registered for the scheme of the given
+    # URI.
     #
+    # @param [String, URI::HTTP] uri
+    #   The URI to infer the media type from.
+    #
+    # @return [Type]
+    #   The media type which handles the specified URI.
+    #
     def Media.guess_from_uri(uri)
       Media.supports_scheme(uri.to_s.scan(/^[^:\/@]+:/).first.chop)
     end
 
     #
-    # Attempts to determine the correct Media type for the specified _path_.
+    # Attempts to determine the correct Media type for a given path.
+    #
+    # @param [String] path
+    #   The path to infer the media type from.
+    #
+    # @return [Type]
+    #   The media type which handles the repository at the specified path.
     #
     def Media.guess_from_path(path)
       path = File.expand_path(path)
 
       Media.directories.each do |directory,media|