record.rb in gcloud-0.7.0

- old
+ new

@@ -1,6 +1,5 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -11,23 +10,27 @@
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/dns/record/list"
 
 module Gcloud
   module Dns
     ##
-    # = DNS Record
+    # # DNS Record
     #
-    # Represents a set of DNS resource records (RRs) for a given #name and #type
-    # in a Zone. Since it is a value object, a newly created Record instance
-    # is transient until it is added to a Zone with Zone#update. Note that
-    # Zone#add and the Zone#update block parameter can be used instead of
-    # Zone#record or +Record.new+ to create new records.
+    # Represents a set of DNS resource records (RRs) for a given
+    # {Gcloud::Dns::Record#name} and {Gcloud::Dns::Record#type} in a
+    # {Gcloud::Dns::Zone}. Since it is a value object, a newly created Record
+    # instance is transient until it is added to a Zone with
+    # {Gcloud::Dns::Zone#update}. Note that {Gcloud::Dns::Zone#add} and the
+    # {Gcloud::Dns::Zone#update} block parameter can be used instead of
+    # {Gcloud::Dns::Zone#record} or `Record.new` to create new records.
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
     #   dns = gcloud.dns
     #   zone = dns.zone "example-com"
@@ -36,57 +39,61 @@
     #   record = zone.record "example.com.", "A", 86400, "1.2.3.4"
     #   zone.records.count #=> 2
     #   change = zone.update record
     #   zone.records.count #=> 3
     #
-    #
     class Record
       ##
-      # The owner of the record. For example: +example.com.+. (+String+)
+      # The owner of the record. For example: `example.com.`.
+      #
+      # @return [String]
+      #
       attr_accessor :name
 
       ##
-      # The identifier of a {supported record type
-      # }[https://cloud.google.com/dns/what-is-cloud-dns#supported_record_types]
-      # . For example: +A+, +AAAA+, +CNAME+, +MX+, or +TXT+. (+String+)
+      # The identifier of a [supported record type
+      # ](https://cloud.google.com/dns/what-is-cloud-dns#supported_record_types)
+      # . For example: `A`, `AAAA`, `CNAME`, `MX`, or `TXT`.
+      #
+      # @return [String]
+      #
       attr_accessor :type
 
       ##
       # The number of seconds that the record can be cached by resolvers.
-      # (+Integer+)
+      #
+      # @return [Integer]
+      #
       attr_accessor :ttl
 
       ##
-      # The array of resource record data, as determined by +type+ and defined
-      # in {RFC 1035 (section 5)}[http://tools.ietf.org/html/rfc1035#section-5]
-      # and {RFC
-      # 1034 (section 3.6.1)}[http://tools.ietf.org/html/rfc1034#section-3.6.1].
+      # The array of resource record data, as determined by `type` and defined
+      # in [RFC 1035 (section 5)](http://tools.ietf.org/html/rfc1035#section-5)
+      # and [RFC
+      # 1034 (section 3.6.1)](http://tools.ietf.org/html/rfc1034#section-3.6.1).
       # For example: ["10 mail.example.com.", "20 mail2.example.com."].
-      # (+Array+ of +String+)
+      #
+      # @return [Array<String>]
+      #
       attr_accessor :data
 
       ##
       # Creates a Record value object.
       #
-      # === Parameters
-      #
-      # +name+::
-      #   The owner of the record. For example: +example.com.+. (+String+)
-      # +type+::
-      #   The identifier of a {supported record
-      #   type}[https://cloud.google.com/dns/what-is-cloud-dns].
-      #   For example: +A+, +AAAA+, +CNAME+, +MX+, or +TXT+. (+String+)
-      # +ttl+::
-      #   The number of seconds that the record can be cached by resolvers.
-      #   (+Integer+)
-      # +data+::
-      #   The resource record data, as determined by +type+ and defined in {RFC
-      #   1035 (section 5)}[http://tools.ietf.org/html/rfc1035#section-5] and
-      #   {RFC 1034
-      #   (section 3.6.1)}[http://tools.ietf.org/html/rfc1034#section-3.6.1].
+      # @param [String] name The owner of the record. For example:
+      #   `example.com.`.
+      # @param [String] type The identifier of a [supported record
+      #   type](https://cloud.google.com/dns/what-is-cloud-dns).
+      #   For example: `A`, `AAAA`, `CNAME`, `MX`, or `TXT`.
+      # @param [Integer] ttl The number of seconds that the record can be cached
+      #   by resolvers.
+      # @param [String, Array<String>] data The resource record data, as
+      #   determined by `type` and defined in [RFC
+      #   1035 (section 5)](http://tools.ietf.org/html/rfc1035#section-5) and
+      #   [RFC 1034
+      #   (section 3.6.1)](http://tools.ietf.org/html/rfc1034#section-3.6.1).
       #   For example: ["10 mail.example.com.", "20 mail2.example.com."].
-      #   (+String+ or +Array+ of +String+)
       #
       def initialize name, type, ttl, data
         fail ArgumentError, "name is required" unless name
         fail ArgumentError, "type is required" unless type
         fail ArgumentError, "ttl is required" unless ttl
@@ -96,54 +103,59 @@
         @ttl = Integer(ttl)
         @data = Array(data)
       end
 
       ##
-      # Returns an array of strings in the zone file format, one
+      # @private Returns an array of strings in the zone file format, one
       # for each element in the record's data array.
-      def to_zonefile_records #:nodoc:
+      def to_zonefile_records
         data.map do |rrdata|
           "#{name} #{ttl} IN #{type} #{rrdata}"
         end
       end
 
       ##
       # Returns a deep copy of the record. Useful for updating records, since
       # the original, unmodified record must be passed for deletion when using
-      # Zone#update.
+      # {Gcloud::Dns::Zone#update}.
+      #
       def dup
         other = super
         other.data = data.map(&:dup)
         other
       end
 
       ##
-      # New Record from a Google API Client object.
-      def self.from_gapi gapi #:nodoc:
+      # @private New Record from a Google API Client object.
+      def self.from_gapi gapi
         new gapi["name"], gapi["type"], gapi["ttl"], gapi["rrdatas"]
       end
 
       ##
-      # Convert the record object to a Google API hash.
-      def to_gapi #:nodoc:
+      # @private Convert the record object to a Google API hash.
+      def to_gapi
         { "name" => name, "type" => type, "ttl" => ttl, "rrdatas" => data }
       end
 
-      def hash #:nodoc:
+      # @private
+      def hash
         [name, type, ttl, data].hash
       end
 
-      def eql? other #:nodoc:
+      # @private
+      def eql? other
         return false unless other.is_a? self.class
         name == other.name && type == other.type &&
           ttl == other.ttl && data == other.data
       end
 
-      def == other #:nodoc:
+      # @private
+      def == other
         self.eql? other
       end
 
-      def <=> other #:nodoc:
+      # @private
+      def <=> other
         return nil unless other.is_a? self.class
         [name, type, ttl, data] <=>
           [other.name, other.type, other.ttl, other.data]
       end
     end