sketchup-api-stubs 0.1.2 → 0.2.0

data/SketchUp/Geom/Vector3d.rb

@@ -11,16 +11,12 @@ class Geom::Vector3d
 
   # Class Methods
 
-  # The linear_combination method is used to create a new vector as a linear
+  # The {.linear_combination} method is used to create a new vector as a linear
   # combination of other vectors. This method is generally used to get a vector
   # at some percentage between two vectors.
   #
   # A linear combination is a standard term for vector math. It is defined as
-  # point = weight1 * point1 + weight2 * point2.
-  #
-  # In addition to the 4-argument form detailed here, you may also call this
-  # method with 6 parameters in the form of:
-  #   - vec = Geom::Vector3d.linear_combination(x, xaxis, y, yaxis, z, zaxis)
+  # vector = weight1 * vector1 + weight2 * vector2.
   #
   # @example
   #   # Create a vector that is a 50%/50% linear combination of two others.
@@ -29,22 +25,26 @@ class Geom::Vector3d
   #   new_vector = Geom::Vector3d.linear_combination(0.5, vec1, 0.5, vec2)
   #   # new_vector will now contain a Vector3d(1.5, 1.5, 0)
   #
-  # @param weight1
-  #   A weight or percentage.
-  #
-  # @param vector1
-  #   The first vector.
+  # @overload linear_combination(weight1, vector1, weight2, vector2)
   #
-  # @param vector2
-  #   The end point of the line.
+  #   @param [Numeric] weight1  A weight or percentage.
+  #   @param [Geom::Vector3d] vector1  The first vector.
+  #   @param [Numeric] weight2  A weight or percentage.
+  #   @param [Geom::Vector3d] vector2  The second vector.
+  #   @return [Geom::Vector3d]
   #
-  # @param weight2
-  #   A weight or percentage.
+  # @overload linear_combination(x, xaxis, y, yaxis, z, zaxis)
   #
-  # @return vector - a Vector3d object
+  #   @param [Numeric] x  A weight or percentage for the x axis.
+  #   @param [Geom::Vector3d] xaxis  The x axis vector.
+  #   @param [Numeric] y  A weight or percentage for the y axis.
+  #   @param [Geom::Vector3d] yaxis  The y axis vector.
+  #   @param [Numeric] z  A weight or percentage for the z axis.
+  #   @param [Geom::Vector3d] zaxis  The z axis vector.
+  #   @return [Geom::Vector3d]
   #
   # @version SketchUp 6.0
-  def self.linear_combination(weight1, vector1, weight2, vector2)
+  def self.linear_combination(*args)
   end
 
   # Instance Methods
@@ -68,25 +68,28 @@ class Geom::Vector3d
   def %(vector)
   end
 
-  # The {#*} method is used to compute the cross product between two vectors.
+  # The {#cross} method is used to compute the cross product between two vectors.
   #
   # The cross product, also called the vector product, is an operation on two
   # vectors. The cross product of two vectors produces a third vector which is
   # perpendicular to the plane in which the first two lie.
   #
-  # This is an alias of the {#cross} method.
-  #
   # @example
-  #   vector1 = Geom::Vector3d.new 1,0,0
-  #   vector2 = Geom::Vector3d.new 0,1,0
+  #   vector1 = Geom::Vector3d.new(1,0,0)
+  #   vector2 = Geom::Vector3d.new(0,1,0)
   #   vector3 = vector1 * vector2
   #
-  # @param vector
+  # @example
+  #   vector = Geom::Vector3d.new(1,0,0)
+  #   vector2 = Geom::Vector3d.new(0,1,0)
+  #   vector3 = vector.cross(vector2)
+  #
+  # @param [Geom::Vector3d] vector
   #   A Vector3d object.
   #
-  # @return vector - a Vector3d object if successful
+  # @return [Geom::Vector3d] the cross of vector1 and vector2
   #
-  # @see #cross
+  # @see #*
   #
   # @version SketchUp 6.0
   def *(vector)
@@ -95,14 +98,14 @@ class Geom::Vector3d
   # The - method is used to add a vector to this one.
   #
   # @example
-  #   vector = Geom::Vector3d.new 0,0,2
-  #   vector2 = Geom::Vector3d.new 0,1,0
+  #   vector = Geom::Vector3d.new(0,0,2)
+  #   vector2 = Geom::Vector3d.new(0,1,0)
   #   new_vector = vector + vector2
   #
   # @param vector2
   #   A Vector3d object.
   #
-  # @return vector - the new vector.
+  # @return [Geom::Vector3d] the new vector.
   #
   # @version SketchUp 6.0
   def +(vector2)
@@ -111,14 +114,14 @@ class Geom::Vector3d
   # The - method is used to subtract a vector from this one.
   #
   # @example
-  #   vector = Geom::Vector3d.new 0,0,2
-  #   vector2 = Geom::Vector3d.new 0,1,0
+  #   vector = Geom::Vector3d.new(0,0,2)
+  #   vector2 = Geom::Vector3d.new(0,1,0)
   #   new_vector = vector - vector2
   #
   # @param vector2
   #   A Vector3d object.
   #
-  # @return vector - the new vector.
+  # @return [Geom::Vector3d] the new vector.
   #
   # @version SketchUp 6.0
   def -(vector2)
@@ -128,14 +131,14 @@ class Geom::Vector3d
   # than another vector's x, y or z value.
   #
   # @example
-  #   vector = Geom::Vector3d.new 0,0,2
-  #   vector2 = Geom::Vector3d.new 0,1,0
+  #   vector = Geom::Vector3d.new(0,0,2)
+  #   vector2 = Geom::Vector3d.new(0,1,0)
   #   lt = vector < vector2
   #
   # @param vector2
   #   A Vector3d object.
   #
-  # @return true if the vector's x, y or z component is less
+  # @return [Boolean] true if the vector's x, y or z component is less
   #
   # @version SketchUp 6.0
   def <(vector2)
@@ -145,8 +148,8 @@ class Geom::Vector3d
   # tolerance.
   #
   # @example
-  #   vector = Geom::Vector3d.new 1,0,0
-  #   vector2 = Geom::Vector3d.new 0,1,0
+  #   vector = Geom::Vector3d.new(1,0,0)
+  #   vector2 = Geom::Vector3d.new(0,1,0)
   #   status = vector == vector2
   #   # Returns false
   #   UI.messagebox status
@@ -154,8 +157,7 @@ class Geom::Vector3d
   # @param vector2
   #   A Vector3d object.
   #
-  # @return status - true if vector1 is equal to vector 2. False if
-  #   they are not equal.
+  # @return [Boolean]
   #
   # @version SketchUp 6.0
   def ==(vector2)
@@ -171,7 +173,7 @@ class Geom::Vector3d
   #   x = vector[0]
   #
   # @example
-  #   vector = Geom::Vector3d.new 1,0,0
+  #   vector = Geom::Vector3d.new(1,0,0)
   #   value = vector[0]
   #   if (value)
   #     UI.messagebox value
@@ -179,10 +181,10 @@ class Geom::Vector3d
   #     UI.messagebox "Failure"
   #   end
   #
-  # @param i
+  # @param [Integer] i
   #   An index into an array of three coordinates.
   #
-  # @return coordinate - the value for the x, y, or z coordinate.
+  # @return [Length] the value for the x, y, or z coordinate.
   #
   # @version SketchUp 6.0
   def [](i)
@@ -194,13 +196,13 @@ class Geom::Vector3d
   # @example
   #   vector[i] = coordinate
   #
-  # @param index
+  # @param [Integer] index
   #   The index for the x, y, or z coordinate.
   #
-  # @param value
+  # @param [Numeric] value
   #   The value for the x, y, or z coordinate.
   #
-  # @return the newly set coordinate value
+  # @return [Numeric] the newly set coordinate value
   #
   # @version SketchUp 6.0
   def []=(index, value)
@@ -210,14 +212,14 @@ class Geom::Vector3d
   # this vector and another vector.
   #
   # @example
-  #   vector1 = Geom::Vector3d.new 1,0,0
-  #   vector2 = Geom::Vector3d.new 0,1,0
+  #   vector1 = Geom::Vector3d.new(1,0,0)
+  #   vector2 = Geom::Vector3d.new(0,1,0)
   #   angle = vector1.angle_between vector2
   #
-  # @param vector2
+  # @param [Geom::Vector3d] vector2
   #   A Vector3d object.
   #
-  # @return angle - an angle (in radians)
+  # @return [Float] an angle (in radians)
   #
   # @version SketchUp 6.0
   def angle_between(vector2)
@@ -229,10 +231,10 @@ class Geom::Vector3d
   # Returns an Array of three vectors [xaxis, yaxis, zaxis]
   #
   # @example
-  #   vector = Geom::Vector3d.new 1,0,0
+  #   vector = Geom::Vector3d.new(1,0,0)
   #   a = vector.axes
   #
-  # @return a - an Array object containing three Vector3d objects
+  # @return [Array(Geom::Vector3d, Geom::Vector3d, Geom::Vector3d)] an Array object containing three Vector3d objects
   #
   # @version SketchUp 6.0
   def axes
@@ -243,10 +245,10 @@ class Geom::Vector3d
   # This method is equivalent to vec2 = Geom::Vector3d.new(vec)
   #
   # @example
-  #   vector = Geom::Vector3d.new 1,0,0
+  #   vector = Geom::Vector3d.new(1,0,0)
   #   vector2 = vector.clone
   #
-  # @return vector2 - a Vector3d object which is the clone of
+  # @return [Geom::Vector3d] a Vector3d object which is the clone of
   #   vector
   #
   # @version SketchUp 6.0
@@ -269,10 +271,10 @@ class Geom::Vector3d
   #   vector2 = Geom::Vector3d.new(0,1,0)
   #   vector3 = vector.cross(vector2)
   #
-  # @param vector
+  # @param [Geom::Vector3d] vector
   #   A Vector3d object.
   #
-  # @return vector - the cross of vector1 and vector2
+  # @return [Geom::Vector3d] the cross of vector1 and vector2
   #
   # @see #*
   #
@@ -301,7 +303,7 @@ class Geom::Vector3d
   #
   # @example
   #   # A vector that runs up the Z axis.
-  #   vector = Geom::Vector3d.new 0,0,1
+  #   vector = Geom::Vector3d.new(0,0,1)
   #   if (vector)
   #     UI.messagebox vector
   #   else
@@ -312,16 +314,26 @@ class Geom::Vector3d
   #
   #   @return [Geom::Vector3d]
   #
-  # @overload initialize(vector2)
+  # @overload initialize(x, y, z)
   #
-  #   @param vector2       A Vector3d object.
+  #   @param [Numeric] x
+  #   @param [Numeric] y
+  #   @param [Numeric] z
   #   @return [Geom::Vector3d]
   #
-  # @overload initialize(x, y, z)
+  # @overload initialize(vector)
+  #
+  #   @param vector [Geom::Vector3d] A Vector3d object.
+  #   @return [Geom::Vector3d]
+  #
+  # @overload initialize(array2d)
+  #
+  #   @param [Array(Numeric, Numeric)] array2d
+  #   @return [Geom::Vector3d]
   #
-  #   @param x             A X value.
-  #   @param y             A Y value.
-  #   @param z             A Z value.
+  # @overload initialize(array3d)
+  #
+  #   @param [Array(Numeric, Numeric, Numeric)] array3d
   #   @return [Geom::Vector3d]
   #
   # @version SketchUp 6.0
@@ -332,11 +344,11 @@ class Geom::Vector3d
   # friendly string.
   #
   # @example
-  #   vector = Geom::Vector3d.new 0,0,1
+  #   vector = Geom::Vector3d.new(0,0,1)
   #   out_string = vector.inspect
   #   puts out_string
   #
-  # @return vector - the Vector3d object
+  # @return [Geom::Vector3d] the Vector3d object
   #
   # @version SketchUp 6.0
   def inspect
@@ -345,10 +357,10 @@ class Geom::Vector3d
   # The length method is used to retrieve the length of the vector.
   #
   # @example
-  #   vector = Geom::Vector3d.new 0,0,1
+  #   vector = Geom::Vector3d.new(0,0,1)
   #   l = vector.length
   #
-  # @return length - the length of the vector
+  # @return [Length] the length of the vector
   #
   # @version SketchUp 6.0
   def length
@@ -358,15 +370,15 @@ class Geom::Vector3d
   # be greater than 0.
   #
   # @example
-  #   vector = Geom::Vector3d.new 0,0,1
+  #   vector = Geom::Vector3d.new(0,0,1)
   #   l = vector.length
-  #   UI.messagebox l
+  #   UI.messagebox(l)
   #   newl = vector.length = 2
   #
-  # @param length
+  # @param [Numeric] length
   #   A length for the vector.
   #
-  # @return length - a newly set length
+  # @return [Numeric] a newly set length
   #
   # @version SketchUp 6.0
   def length=(length)
@@ -376,10 +388,10 @@ class Geom::Vector3d
   # of another.
   #
   # @example
-  #   vector = Geom::Vector3d.new 0,0,2
+  #   vector = Geom::Vector3d.new(0,0,2)
   #   vector2 = vector.normalize
   #
-  # @return vector2 - a normalized Vector3d object
+  # @return [Geom::Vector3d] a new normalized Vector3d object
   #
   # @version SketchUp 6.0
   def normalize
@@ -391,10 +403,10 @@ class Geom::Vector3d
   # Another way to do this is vec.length = 1
   #
   # @example
-  #   vector = Geom::Vector3d.new 0,0,2
+  #   vector = Geom::Vector3d.new(0,0,2)
   #   vector.normalize!
   #
-  # @return vector2 - a normalized Vector3d object
+  # @return [Geom::Vector3d] a normalized Vector3d object
   #
   # @version SketchUp 6.0
   def normalize!
@@ -404,13 +416,12 @@ class Geom::Vector3d
   # another vector to within tolerance.
   #
   # @example
-  #   status = vector.parallel? vector2
+  #   status = vector.parallel?(vector2)
   #
-  # @param vector2
+  # @param [Geom::Vector3d] vector2
   #   A Vector3d object.
   #
-  # @return status - true if vector and vector2 are parallel. False
-  #   if they are not parallel.
+  # @return [Boolean]
   #
   # @return [Boolean]
   #
@@ -422,15 +433,14 @@ class Geom::Vector3d
   # perpendicular to another vector to within tolerance.
   #
   # @example
-  #   vector = Geom::Vector3d.new 0,0,1
-  #   vector2 = Geom::Vector3d.new 0,1,0
-  #   status = vector.perpendicular? vector2
+  #   vector = Geom::Vector3d.new(0,0,1)
+  #   vector2 = Geom::Vector3d.new(0,1,0)
+  #   status = vector.perpendicular?(vector2)
   #
-  # @param vector2
+  # @param [Geom::Vector3d] vector2
   #   A Vector3d object.
   #
-  # @return status - true if vector and vector2 are parallel. False
-  #   if they are not parallel.
+  # @return [Boolean]
   #
   # @return [Boolean]
   #
@@ -444,7 +454,7 @@ class Geom::Vector3d
   # @example
   #   vector2 = vector.reverse
   #
-  # @return vector2 - a Vector3d object that is the reverse of
+  # @return [Geom::Vector3d] a Vector3d object that is the reverse of
   #   vector
   #
   # @version SketchUp 6.0
@@ -456,7 +466,7 @@ class Geom::Vector3d
   # @example
   #   vector.reverse!
   #
-  # @return vector2 - a Vector3d object that is the reverse of
+  # @return [Geom::Vector3d] a Vector3d object that is the reverse of
   #   vector
   #
   # @version SketchUp 6.0
@@ -467,15 +477,14 @@ class Geom::Vector3d
   # and in the same direction as another vector to within tolerance.
   #
   # @example
-  #   vector = Geom::Vector3d.new 0,0,1
-  #   vector2 = Geom::Vector3d.new 0,1,0
-  #   status = vector.samedirection? vector2
+  #   vector = Geom::Vector3d.new(0,0,1)
+  #   vector2 = Geom::Vector3d.new(0,1,0)
+  #   status = vector.samedirection?(vector2)
   #
-  # @param vector2
+  # @param [Geom::Vector3d] vector2
   #   A Vector3d object.
   #
-  # @return status - true if vector and vector2 are in the same
-  #   direction. False if they are not in the same direction.
+  # @return [Boolean]
   #
   # @return [Boolean]
   #
@@ -496,20 +505,25 @@ class Geom::Vector3d
   #   vec.set!(vec2)
   #
   # @example
-  #   vector = Geom::Vector3d.new 0,0,1
+  #   vector = Geom::Vector3d.new(0,0,1)
   #   vector.set! 1,0,0
   #
   # @overload set!(x, y, z)
   #
-  #   @param x             The x value for the vector.
-  #   @param y             The y value for the vector.
-  #   @param z             The z value for the vector.
-  #   @return              vector - The newly set Vector3d object
+  #   @param [Numeric] x
+  #   @param [Numeric] y
+  #   @param [Numeric] z
+  #   @return [Geom::Vector3d]
+  #
+  # @overload set!(vector)
   #
-  # @overload set!(vector2)
+  #   @param vector [Geom::Vector3d]
+  #   @return [Geom::Vector3d]
+  #
+  # @overload set!(array3d)
   #
-  #   @param vector2       A Vector3d object.
-  #   @return              vector - The newly set Vector3d object
+  #   @param array3d [Array(Numeric, Numeric, Numeric)]
+  #   @return [Geom::Vector3d]
   #
   # @version SketchUp 6.0
   def set!(*args)
@@ -521,7 +535,7 @@ class Geom::Vector3d
   # @example
   #   a = vector.to_a
   #
-  # @return a - the coordinates of the vector in an array
+  # @return [Array(Length, Length, Length)] the coordinates of the vector in an array
   #
   # @version SketchUp 6.0
   def to_a
@@ -530,40 +544,40 @@ class Geom::Vector3d
   # The to_s method is used to format the vector as a String.
   #
   # @example
-  #   vector = Geom::Vector3d.new 0,0,1
+  #   vector = Geom::Vector3d.new(0,0,1)
   #   out_string = vector.to_s
   #   puts out_string
   #
-  # @return s - a string representation of vector
+  # @return [String] a string representation of vector
   #
   # @version SketchUp 6.0
   def to_s
   end
 
-  # Apply a Transformation to a vector. The vector itself is modified.
+  # Apply a Transformation to a vector, returning a new vector. The original
+  # vector is unchanged by this method.
   #
   # @example
-  #   vector.transform! transformation
+  #   vector2 = vector.transform(transformation)
   #
-  # @param transform
+  # @param [Geom::Transformation] transform
   #   A Transformation object to apply to the vector.
   #
-  # @return vector - the vector
+  # @return [Geom::Vector3d] the newly transformed vector
   #
   # @version SketchUp 6.0
   def transform(transform)
   end
 
-  # Apply a Transformation to a vector, returning a new vector. The original
-  # vector is unchanged by this method.
+  # Apply a Transformation to a vector. The vector itself is modified.
   #
   # @example
-  #   vector2 = vector.transform! transformation
+  #   vector.transform!(transformation)
   #
-  # @param transform
+  # @param [Geom::Transformation] transform
   #   A Transformation object to apply to the vector.
   #
-  # @return vector2 - the newly transformed vector
+  # @return [Geom::Vector3d] the transformed vector
   #
   # @version SketchUp 6.0
   def transform!(transform)
@@ -574,11 +588,10 @@ class Geom::Vector3d
   # This is equivalent to vec.length == 1.0
   #
   # @example
-  #   vector = Geom::Vector3d.new 0,0,1
+  #   vector = Geom::Vector3d.new(0,0,1)
   #   status = vector.unitvector?
   #
-  # @return status - true if the vector is a unit vector. False if
-  #   the vector is not a unit vector.
+  # @return [Boolean]
   #
   # @return [Boolean]
   #
@@ -591,14 +604,13 @@ class Geom::Vector3d
   #
   # @example
   #   # A zero length vector will be invalid
-  #   vector = Geom::Vector3d.new 0,0,0
+  #   vector = Geom::Vector3d.new(0,0,0)
   #   status = vector.valid?
   #   # A non-zero length vector is valid
-  #   vector = Geom::Vector3d.new 0,0,1
+  #   vector = Geom::Vector3d.new(0,0,1)
   #   status = vector.valid?
   #
-  # @return status - true if the vector is valid. false if the
-  #   vector is not valid.
+  # @return [Boolean]
   #
   # @return [Boolean]
   #
@@ -611,7 +623,7 @@ class Geom::Vector3d
   # @example
   #   x = vector.x
   #
-  # @return x - the x coordinate of the vector
+  # @return [Length] the x coordinate of the vector
   #
   # @version SketchUp 6.0
   def x
@@ -623,10 +635,10 @@ class Geom::Vector3d
   #   vector = Geom::Vector3d.new 1,2,3
   #   x = vector.x = 10
   #
-  # @param x
+  # @param [Numeric] x
   #   The x coordinate for the vector.
   #
-  # @return x - the newly set x coordinate for the vector
+  # @return [Numeric] the newly set x coordinate for the vector
   #
   # @version SketchUp 6.0
   def x=(x)
@@ -635,10 +647,10 @@ class Geom::Vector3d
   # The y method is used to retrieve the y coordinate of the vector.
   #
   # @example
-  #   vector = Geom::Vector3d.new 1,2,3
+  #   vector = Geom::Vector3d.new(1,2,3)
   #   y = vector.y
   #
-  # @return y - the y coordinate of the vector
+  # @return [Length] the y coordinate of the vector
   #
   # @version SketchUp 6.0
   def y
@@ -647,13 +659,13 @@ class Geom::Vector3d
   # Set the y coordinate of the vector.
   #
   # @example
-  #   vector = Geom::Vector3d.new 1,2,3
+  #   vector = Geom::Vector3d.new(1,2,3)
   #   y = vector.y = 10
   #
-  # @param y
+  # @param [Numeric] y
   #   The y coordinate for the vector.
   #
-  # @return y - the newly set y coordinate for the vector
+  # @return [Numeric] the newly set y coordinate for the vector
   #
   # @version SketchUp 6.0
   def y=(y)
@@ -662,10 +674,10 @@ class Geom::Vector3d
   # Get the z coordinate of the vector.
   #
   # @example
-  #   vector = Geom::Vector3d.new 1,2,3
+  #   vector = Geom::Vector3d.new(1,2,3)
   #   z = vector.z
   #
-  # @return z - the z coordinate of the vector
+  # @return [Length] the z coordinate of the vector
   #
   # @version SketchUp 6.0
   def z
@@ -674,13 +686,13 @@ class Geom::Vector3d
   # Set the z coordinate of the vector.
   #
   # @example
-  #   vector = Geom::Vector3d.new 1,2,3
+  #   vector = Geom::Vector3d.new(1,2,3)
   #   z = vector.z = 10
   #
-  # @param z
+  # @param [Numeric] z
   #   The z coordinate for the vector.
   #
-  # @return z - the newly set z coordinate for the vector
+  # @return [Numeric] the newly set z coordinate for the vector
   #
   # @version SketchUp 6.0
   def z=(z)