transaction.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,20 +10,22 @@
 # 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.
 
+
 module Gcloud
   module Dns
     class Zone
       ##
-      # = DNS Zone Transaction
+      # # DNS Zone Transaction
       #
-      # This object is used by Zone#update when passed a block. These methods
+      # This object is used by {Zone#update} when passed a block. These methods
       # are used to update the records that are sent to the Google Cloud DNS
       # API.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   dns = gcloud.dns
       #   zone = dns.zone "example-com"
@@ -37,44 +38,39 @@
       #       cname.ttl = 86400 # only change the TTL
       #     end
       #   end
       #
       class Transaction
-        attr_reader :additions, :deletions #:nodoc:
+        # @private
+        attr_reader :additions, :deletions
 
         ##
-        # Creates a new transaction.
-        def initialize zone #:nodoc:
+        # @private Creates a new transaction.
+        def initialize zone
           @zone = zone
           @additions = []
           @deletions = []
         end
 
         ##
         # Adds a record to the Zone.
         #
-        # === Parameters
+        # @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: `192.0.2.1` or `example.com.`.
         #
-        # +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]. For
-        #   example: +192.0.2.1+ or +example.com.+. (+String+ or +Array+ of
-        #   +String+)
-        #
-        # === Example
-        #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
         #   dns = gcloud.dns
         #   zone = dns.zone "example-com"
@@ -88,21 +84,17 @@
 
         ##
         # Removes records from the Zone. The records are looked up before they
         # are removed.
         #
-        # === Parameters
+        # @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`.
         #
-        # +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+)
-        #
-        # === Example
-        #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
         #   dns = gcloud.dns
         #   zone = dns.zone "example-com"
@@ -113,34 +105,28 @@
         def remove name, type
           @deletions += @zone.records(name, type).all
         end
 
         ##
-        # Replaces existing records on the Zone. Records matching the +name+ and
-        # +type+ are replaced.
+        # Replaces existing records on the Zone. Records matching the `name` and
+        # `type` are replaced.
         #
-        # === Parameters
+        # @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: `192.0.2.1` or `example.com.`.
         #
-        # +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]. For
-        #   example: +192.0.2.1+ or +example.com.+. (+String+ or +Array+ of
-        #   +String+)
-        #
-        # === Example
-        #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
         #   dns = gcloud.dns
         #   zone = dns.zone "example-com"
@@ -153,23 +139,21 @@
           remove name, type
           add name, type, ttl, data
         end
 
         ##
-        # Modifies records on the Zone. Records matching the +name+ and +type+
+        # Modifies records on the Zone. Records matching the `name` and `type`
         # are yielded to the block where they can be modified.
         #
-        # === Parameters
+        # @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`.
+        # @yield [record] a block yielding each matching record
+        # @yieldparam [Record] record the record to be modified
         #
-        # +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+)
-        #
-        # === Example
-        #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
         #   dns = gcloud.dns
         #   zone.update do |tx|