sketchup-api-stubs 0.7.2 → 0.7.7

data/lib/sketchup-api-stubs/stubs/Sketchup/LayersObserver.rb

@@ -1,10 +1,11 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
-# This observer interface is implemented to react to layers events. To
-# implement this observer, create a Ruby class of this type, override the
-# desired methods, and add an instance of the observer to the objects of
-# interests.
+# This observer interface is implemented to react to layers events.
+#
+# @abstract To implement this observer, create a Ruby class of this type, override the
+#   desired methods, and add an instance of the observer to the objects of
+#   interests.
 #
 # @example
 #   class MyLayersObserver < Sketchup::LayersObserver
@@ -88,6 +89,87 @@ class Sketchup::LayersObserver
   def onLayerChanged(layers, layer)
   end
 
+  # The {#onLayerFolderAdded} method is called when a layer folder is added
+  # to a model.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   class MyLayersObserver < Sketchup::LayersObserver
+  #     def onLayerFolderAdded(layers, layer_folder)
+  #       puts "onLayerFolderAdded: #{layer_folder.name}"
+  #     end
+  #   end
+  #
+  #   model = Sketchup.active_model
+  #   model.layers.add_observer(MyLayersObserver.new)
+  #   folder = model.layers.add_folder("Hello World")
+  #
+  # @param [Sketchup::Layers] layers
+  #
+  # @param [Sketchup::LayerFolder] layer_folder
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 2021.0
+  def onLayerFolderAdded(layers, layer_folder)
+  end
+
+  # The {#onLayerFolderChanged} method is called when a layer folder changes
+  # one of its properties.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   class MyLayersObserver < Sketchup::LayersObserver
+  #     def onLayerFolderChanged(layers, layer_folder)
+  #       puts "onLayerFolderChanged: #{layer_folder.name}"
+  #     end
+  #   end
+  #
+  #   model = Sketchup.active_model
+  #   model.layers.add_observer(MyLayersObserver.new)
+  #   folder = model.layers.add_folder("Hello World")
+  #   folder.name = "Hello Universe"
+  #   folder.visible = false
+  #
+  # @param [Sketchup::Layers] layers
+  #
+  # @param [Sketchup::LayerFolder] layer_folder
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 2021.0
+  def onLayerFolderChanged(layers, layer_folder)
+  end
+
+  # The {#onLayerFolderRemoved} method is called when a layer folder is removed
+  # from a model.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   class MyLayersObserver < Sketchup::LayersObserver
+  #     def onLayerFolderRemoved(layers, layer_folder)
+  #       puts "onLayerRemoved: #{layer_folder.name}"
+  #     end
+  #   end
+  #
+  #   model = Sketchup.active_model
+  #   model.layers.add_observer(MyLayersObserver.new)
+  #   folder = model.layers.add_folder("Hello World")
+  #   model.layers.remove_folder(folder)
+  #
+  # @param [Sketchup::Layers] layers
+  #
+  # @param [Sketchup::LayerFolder] layer_folder
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 2021.0
+  def onLayerFolderRemoved(layers, layer_folder)
+  end
+
   # The {#onLayerRemoved} method is called when a layer is removed from a model.
   #
   # @example
@@ -111,6 +193,37 @@ class Sketchup::LayersObserver
   def onLayerRemoved(layers, layer)
   end
 
+  # The {#onParentFolderChanged} method is called when a layer changes parent
+  # folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   class MyLayersObserver < Sketchup::LayersObserver
+  #     def onParentFolderChanged(layers, layer)
+  #       puts "onParentFolderChange: #{layer.name}"
+  #     end
+  #   end
+  #
+  #   model = Sketchup.active_model
+  #   model.layers.add_observer(MyLayersObserver.new)
+  #   layer = model.layers.add_layer("World")
+  #   folder = model.layers.add_folder("Hello")
+  #   layer.folder = folder
+  #
+  # @note When a folder changes parent {#onLayerFolderRemoved} and
+  #   {#onLayerFolderAdded} triggers.
+  #
+  # @param [Sketchup::Layers] layers
+  #
+  # @param [Sketchup::Layer] layer
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 2021.0
+  def onParentFolderChanged(layers, layer)
+  end
+
   # The {#onRemoveAllLayers} method is called when all layer are removed from a
   # model.
   #

data/lib/sketchup-api-stubs/stubs/Sketchup/Licensing.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The +Sketchup::Licensing+ module contains methods for
@@ -10,7 +10,7 @@
 # than their Ruby API counterparts.
 #
 # For more details, see:
-# {Developer Center Licensing Tutorial}[https://extensions.sketchup.com/en/developer_center/tutorial_licensing]
+# {Licensing Example}[https://github.com/SketchUp/sketchup-ruby-api-tutorials/tree/master/examples/99_license]
 #
 # @version SketchUp 2015
 module Sketchup::Licensing

data/lib/sketchup-api-stubs/stubs/Sketchup/Licensing/ExtensionLicense.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Sketchup::Licensing::ExtensionLicense class is used to store extension

data/lib/sketchup-api-stubs/stubs/Sketchup/LineStyle.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # This provides a way for SketchUp to customize a line style and be set on a

data/lib/sketchup-api-stubs/stubs/Sketchup/LineStyles.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # Provides access to the different line style objects in the model.
@@ -74,18 +74,6 @@ class Sketchup::LineStyles < Sketchup::Entity
   def each
   end
 
-  # The {#size} method returns the number of line styles that SketchUp supports.
-  #
-  # @example
-  #   line_styles = Sketchup.active_model.line_styles
-  #   line_styles.size
-  #
-  # @return [Integer] The count of line styles.
-  #
-  # @version SketchUp 2019
-  def length
-  end
-
   # The {#names} method return the support line styles as strings.
   #
   # @example
@@ -108,6 +96,7 @@ class Sketchup::LineStyles < Sketchup::Entity
   # @version SketchUp 2019
   def size
   end
+  alias_method :length, :size
 
   # The {#to_a} method returns an array of all the line styles.
   #

data/lib/sketchup-api-stubs/stubs/Sketchup/Loop.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # Loop is a low level topology class that will not need to be used often. A

data/lib/sketchup-api-stubs/stubs/Sketchup/Material.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Material class represents a texture or color that can be applied to
@@ -358,20 +358,18 @@ class Sketchup::Material < Sketchup::Entity
   #
   # @overload texture=(filename)
   #
-  #   @param filename [String] The file path to the texture the material should use.
-  #   @return [String]
+  #   @param [String] filename
+  #     The file path to the texture the material should use.
   #
   # @overload texture=(properties)
   #
-  #   @param properties [Array(String, Integer, Integer)] An array with the
-  #     texture filename and optionally the width and height in model units.
-  #   @return [Array(String, Integer, Integer)]
+  #   @param [Array(String, Length, Length)] properties
+  #     An array with the texture file path and optionally the width and height.
   #
   # @overload texture=(image_rep)
   #
   #   @param [Sketchup::ImageRep] image_rep The pixel data representing the
   #     texture. (Added in SketchUp 2018)
-  #   @return [Sketchup::ImageRep]
   #
   # @version SketchUp 6.0
   def texture=(arg)
@@ -401,8 +399,8 @@ class Sketchup::Material < Sketchup::Entity
   #     material.write_thumbnail(thumbnail_file, 128)
   #   }
   #
-  # @param [String] filename
-  #   The file name for the thumbnail.
+  # @param [String] path
+  #   The file path for the thumbnail.
   #
   # @param [Integer] resolution
   #   The resolution of the thumbnail.
@@ -410,7 +408,7 @@ class Sketchup::Material < Sketchup::Entity
   # @return [Boolean] true if successful, false if unsuccessful.
   #
   # @version SketchUp 8.0 M1
-  def write_thumbnail(filename, resolution)
+  def write_thumbnail(path, resolution)
   end
 
 end

data/lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # A collection of Materials objects. Each model contains a Materials collection
@@ -29,13 +29,14 @@ class Sketchup::Materials < Sketchup::Entity
   #
   # @overload [](index)
   #
-  #   @param index [Integer] A number representing the material's index in an array
-  #                        of Material objects.
+  #   @param [Integer] index
+  #    A number representing the material's index in an array of Material
+  #    objects.
   #   @return [Sketchup::Material, nil] a Material object on success, Nil on failure
   #
   # @overload [](name)
   #
-  #   @param name [String] The name of the material.
+  #   @param [String] name The name of the material.
   #   @return [Sketchup::Material, nil] a Material object on success, Nil on failure
   #
   # @version SketchUp 6.0
@@ -89,13 +90,14 @@ class Sketchup::Materials < Sketchup::Entity
   #
   # @overload [](index)
   #
-  #   @param index [Integer] A number representing the material's index in an array
-  #                        of Material objects.
+  #   @param [Integer] index
+  #    A number representing the material's index in an array of Material
+  #    objects.
   #   @return [Sketchup::Material, nil] a Material object on success, Nil on failure
   #
   # @overload [](name)
   #
-  #   @param name [String] The name of the material.
+  #   @param [String] name The name of the material.
   #   @return [Sketchup::Material, nil] a Material object on success, Nil on failure
   #
   # @version SketchUp 6.0
@@ -147,7 +149,7 @@ class Sketchup::Materials < Sketchup::Entity
   def current=(material)
   end
 
-  # The each method is used to iterate through all of the materials.
+  # The {#each} method is used to iterate through all of the materials.
   #
   # @example
   #   model = Sketchup.active_model
@@ -155,6 +157,11 @@ class Sketchup::Materials < Sketchup::Entity
   #     puts material.display_name
   #   }
   #
+  # @note Don't remove content from this collection while iterating over it with
+  #   {#each}. This would change the size of the collection and cause elements to
+  #   be skipped as the indices change. Instead copy the current collection to an
+  #   array using +to_a+ and then use +each+ on the array, when removing content.
+  #
   # @return [nil]
   #
   # @version SketchUp 6.0
@@ -184,7 +191,7 @@ class Sketchup::Materials < Sketchup::Entity
 
   # The {#load} method is used to load a material from file into the model.
   #
-  # If a matching material exist in the model that will be returned instead.
+  # If a matching material exist in the model it will be returned instead.
   #
   # @example
   #   # Load a material from the shipped SketchUp library. (SketchUp 2016)

data/lib/sketchup-api-stubs/stubs/Sketchup/MaterialsObserver.rb

@@ -1,10 +1,11 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
-# This observer interface is implemented to react to materials events. To
-# implement this observer, create a Ruby class of this type, override the
-# desired methods, and add an instance of the observer to the objects of
-# interests.
+# This observer interface is implemented to react to materials events.
+#
+# @abstract To implement this observer, create a Ruby class of this type, override the
+#   desired methods, and add an instance of the observer to the objects of
+#   interests.
 #
 # @example
 #   class MyMaterialsObserver < Sketchup::MaterialsObserver

data/lib/sketchup-api-stubs/stubs/Sketchup/Menu.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # An interface to a menu.
@@ -20,9 +20,9 @@ class Sketchup::Menu
   #   menu = UI.menu('Plugins')
   #   menu.add_item("Test") { puts 'Hello World' }
   #
-  # @overload add_item(menu, &block)
+  # @overload add_item(title, &block)
   #
-  #   @param [String] menu The name of the menu to add.
+  #   @param [String] title
   #   @yield  A block that will be invoked when the menu item is selected.
   #   @return [Integer] A unique integer id for the added menu item.
   #
@@ -35,7 +35,7 @@ class Sketchup::Menu
   def add_item(*args)
   end
 
-  # The add_separator method is used to add a menu separator to a menu.
+  # The {#add_separator} method is used to add a menu separator to a menu.
   #
   # @example
   #   plugins_menu = UI.menu("Plugins")
@@ -47,7 +47,7 @@ class Sketchup::Menu
   def add_separator
   end
 
-  # The add_submenu method is used to add a sub-menu to a menu.
+  # The {#add_submenu} method is used to add a sub-menu to a menu.
   #
   # @example
   #   plugins_menu = UI.menu("Plugins")
@@ -65,7 +65,7 @@ class Sketchup::Menu
   def add_submenu(title)
   end
 
-  # The set_validation_proc method is used to identify the menu validation
+  # The {#set_validation_proc} method is used to specify the menu validation
   # procedure. Your procedure should return either MF_ENABLED, MF_DISABLED,
   # MF_CHECKED, MF_UNCHECKED, or MF_GRAYED.
   #
@@ -80,16 +80,14 @@ class Sketchup::Menu
   #     end
   #   }
   #
-  # @param [String] menu
-  #   A string name of the menu to add.
-  #
-  # @return [Integer] a unique numerical item id for the menu
+  # @param [Integer] item
+  #   The numerical identifier for the menu item.
   #
   # @version SketchUp 6.0
   #
   # @yield A method that will be invoked when the menu item is
   #   selected.
-  def set_validation_proc(menu, &block)
+  def set_validation_proc(item, &block)
   end
 
 end

data/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # This is the interface to a SketchUp model. The model is the 3D drawing that
@@ -44,6 +44,9 @@ class Sketchup::Model
 
   # Constants
 
+  LOAD_STATUS_SUCCESS = nil # Stub value.
+  LOAD_STATUS_SUCCESS_MORE_RECENT = nil # Stub value.
+
   Make = nil # Stub value.
   MakeTrial = nil # Stub value.
   ProLicensed = nil # Stub value.
@@ -57,6 +60,7 @@ class Sketchup::Model
   VERSION_2018 = nil # Stub value.
   VERSION_2019 = nil # Stub value.
   VERSION_2020 = nil # Stub value.
+  VERSION_2021 = nil # Stub value.
   VERSION_3 = nil # Stub value.
   VERSION_4 = nil # Stub value.
   VERSION_5 = nil # Stub value.
@@ -66,15 +70,19 @@ class Sketchup::Model
 
   # Instance Methods
 
-  # The abort_operation method aborts the current operation started with the
+  # The {#abort_operation} method aborts the current operation started with the
   # start_operation method.
   #
-  # The abort_operation method is normally called from inside of a rescue clause
-  # to cancel an operation if something goes wrong.
+  # The {#abort_operation} method is normally called from inside of a rescue
+  # clause to cancel an operation if something goes wrong.
   #
   # @example
   #   status = model.abort_operation
   #
+  # @note Never abort a transparent operation. Doing so would abort the operation
+  #   it chains to. Instead, try to clean up and simply commit in order to make
+  #   sure the operation is closed.
+  #
   # @return [Boolean] true if successful, false if unsuccessful
   #
   # @version SketchUp 6.0
@@ -155,37 +163,6 @@ class Sketchup::Model
 
   # The {#active_path=} method is used to open a given instance path for editing.
   #
-  # It is expected that no entities are modified in an operation that
-  # opens/closes instances.
-  #
-  # To ensure that undo/redo is done correctly this method breaks up any open
-  # Ruby operations into a set of chained operations:
-  #
-  # If the API user tries to do this:
-  #
-  #     model.start_operation('...', true)
-  #     model.entities.add_face(...)
-  #     model.active_path = instance_path
-  #     model.entities.add_face(...)
-  #     model.commit_operation
-  #
-  # Then the method will break it up to something like this:
-  #
-  #     model.start_operation('...', true)
-  #     model.entities.add_face(...)
-  #     model.commit_operation
-  #
-  #     model.start_operation('...', true, false, true)
-  #     model.active_path = instance_path
-  #     model.commit_operation
-  #
-  #     model.start_operation('...', true, false, true)
-  #     model.entities.add_face(...)
-  #     model.commit_operation
-  #
-  # For the end user this will be experienced as a single operation.
-  # For the API user the side-effect is multiple transaction notifications.
-  #
   # @example Open an instance
   #   model = Sketchup.active_model
   #   instance = model.active_entities.grep(Sketchup::ComponentInstance).first
@@ -201,8 +178,37 @@ class Sketchup::Model
   #   on the given path. A definition cannot be edited if any of its instances
   #   are locked.
   #
-  # @note Open/close operations are special operations in SketchUp which has to
-  #   be treated with special care.
+  # @note Since changing the active entities in SketchUp also changes what
+  #   coordinate system is used, entities can't be modified in the same operation
+  #   as the active entities changes. The API handles this automatically by
+  #   starting and committing transparent operations as needed.
+  #
+  #   If the API user tries to do this:
+  #
+  #       model.start_operation('...', true)
+  #       model.entities.add_face(...)
+  #       model.active_path = instance_path
+  #       model.entities.add_face(...)
+  #       model.commit_operation
+  #
+  #   Then SketchUp will automatically break it up to something like to this:
+  #
+  #       model.start_operation('...', true)
+  #       model.entities.add_face(...)
+  #       model.commit_operation
+  #
+  #       model.start_operation('...', true, false, true)
+  #       model.active_path = instance_path
+  #       model.commit_operation
+  #
+  #       model.start_operation('...', true, false, true)
+  #       model.entities.add_face(...)
+  #       model.commit_operation
+  #
+  #   For the end user this will be experienced as a single operation.
+  #
+  #   For the API user the side-effect is multiple transaction notifications to
+  #   {Sketchup::ModelObserver}s.
   #
   # @param [Sketchup::InstancePath, Array<Sketchup::ComponentInstance, Sketchup::Group>, nil] instance_path
   #   Passing +nil+ or an empty array will close all open instances.
@@ -214,6 +220,8 @@ class Sketchup::Model
   # @raise [ArgumentError] if the instance path contains instances who's
   #   siblings are locked.
   #
+  # @raise [ArgumentError] if the instance path contains Live Components.
+  #
   # @return [Sketchup::Model]
   #
   # @version SketchUp 2020.0
@@ -360,13 +368,14 @@ class Sketchup::Model
   def behavior
   end
 
-  # The {#bounds} method retrieves the bounding box of the model.
+  # The {#bounds} method is used to retrieve the {Geom::BoundingBox} bounding the
+  # contents of a {Sketchup::Model}.
   #
   # @example
   #   model = Sketchup.active_model
   #   bounds = model.bounds
   #
-  # @return [Geom::BoundingBox] bounding box for the model if successful
+  # @return [Geom::BoundingBox]
   #
   # @version SketchUp 6.0
   def bounds
@@ -614,15 +623,15 @@ class Sketchup::Model
   #                    :ifc_types => ['IfcBuilding', 'IfcDoor']}
   #   status = model.export('c:/my_export.ifc', options_hash)
   #
-  # @overload export(filename, show_summary = false)
+  # @overload export(path, show_summary = false)
   #
-  #   @param [String] filename The name of the file to export.
+  #   @param [String] path The name of the file to export.
   #   @param [Boolean] show_summary Boolean to show summary dialog.
   #   @return [Boolean]
   #
-  # @overload export(filename, options)
+  # @overload export(path, options)
   #
-  #   @param [String] filename The name of the file to export.
+  #   @param [String] path The path to save the export at.
   #   @param [Hash] options
   #   @return [Boolean]
   #
@@ -689,15 +698,54 @@ class Sketchup::Model
   #   entities = model.find_entity_by_persistent_id(id1, id2, id3)
   #   entities = model.find_entity_by_persistent_id([id1, id2, id3])
   #
-  # @param [Array<Integer>] ids_or_array
-  #   Pass either a series of ids or a
-  #   single array containing persistent ids.
-  #
-  # @return [Array<Sketchup::Entity, nil>] Returns an array with
-  #   {Sketchup::Entity} objects for each id found and nil otherwise.
+  # @example Limit search by scope
+  #   model = Sketchup.active_model
+  #   edge_pid = model.entities.add_line([0,0,0], [9,9,9]).persistent_id
+  #   layer_pid = model.layers.add('Hello World').persistent_id
+  #
+  #   # Search in all scopes:
+  #   entities = model.find_entity_by_persistent_id(edge_pid, layer_pid)
+  #   # => [#<Sketchup::Edge:0x000002567da4a8f0>, #<Sketchup::Layer:0x000002567da49e50>]
+  #
+  #   # Search in layer scope:
+  #   entities = model.find_entity_by_persistent_id(edge_pid, layer_pid, layers: true)
+  #   # => [nil, #<Sketchup::Layer:0x000002567da49e50>]
+  #
+  # @overload find_entity_by_persistent_id(ids_or_array)
+  #
+  #   @param [Array<Integer>] ids_or_array Pass either a series of ids or a
+  #     single array containing persistent ids.
+  #
+  #   @return [Array<Sketchup::Entity, nil>] Returns an array with
+  #     {Sketchup::Entity} objects for each id found and nil otherwise.
+  #
+  # @overload find_entity_by_persistent_id(ids_or_array, **scope)
+  #
+  #   @version SketchUp 2020.2
+  #   @param [Array<Integer>] ids_or_array Pass either a series of ids or a
+  #     single array containing persistent ids.
+  #   @param [Hash<Symbol, Boolean>] scope Limit the scope of the search to the
+  #     given scope categories.
+  #   @option [Boolean] scope :entities Search entities parent to
+  #     {Sketchup::Entities}.
+  #   @option [Boolean] scope :layers Search {Sketchup::Layers} for
+  #     {Sketchup::Layer} entities.
+  #   @option [Boolean] scope :layer_folders Search {Sketchup::Layers} for
+  #     {Sketchup::LayerFolder} entities.
+  #   @option [Boolean] scope :materials Search {Sketchup::Materials} for
+  #     {Sketchup::Material} entities.
+  #   @option [Boolean] scope :pages Search {Sketchup::Pages} for
+  #     {Sketchup::Page} entities.
+  #   @option [Boolean] scope :styles Search {Sketchup::Styles} for
+  #     {Sketchup::Style} entities.
+  #   @option [Boolean] scope :definitions Search {Sketchup::DefinitionList} for
+  #     {Sketchup::ComponentDefinition} entities.
+  #
+  #   @return [Array<Sketchup::Entity, nil>] Returns an array with
+  #     {Sketchup::Entity} objects for each id found and nil otherwise.
   #
   # @version SketchUp 2017
-  def find_entity_by_persistent_id(ids_or_array)
+  def find_entity_by_persistent_id(*args)
   end
 
   # This methods determines if the model is georeferenced.
@@ -805,6 +853,9 @@ class Sketchup::Model
   # The import method is used to load a file by recognizing the file extension
   # and calling appropriate importer.
   #
+  # See {Sketchup::DefinitionList#import} for importing a 3d model file as a
+  # component definition, without activating the UI for placing an instance.
+  #
   # See the {file:pages/importer_options.md Importer Options} file for information
   # on creating a valid hash for the various importers.
   #
@@ -820,16 +871,16 @@ class Sketchup::Model
   #               :show_summary => true }
   #   status = model.import("filename", options)
   #
-  # @overload import(filename, options)
+  # @overload import(path, options)
   #
-  #   @param [String] filename The input filename.
+  #   @param [String] path The input file path.
   #   @param [Hash] options The options.
   #   @return [Boolean]
   #
-  # @overload import(filename, show_summary = false)
+  # @overload import(path, show_summary = false)
   #
   #   @note This variant is for SketchUp 2017 and earlier.
-  #   @param [String] filename The input filename.
+  #   @param [String] path The input file path.
   #   @param [Boolean] show_summary Show the summary dialog.
   #   @return [Boolean]
   #
@@ -1031,7 +1082,7 @@ class Sketchup::Model
   # @example
   #   # Output all options available.
   #   options_manager = Sketchup.active_model.options
-  #   options_manager.keys.each { |options_provider|
+  #   options_manager.each { |options_provider|
   #     puts options_provider.name
   #     options_provider.each { |key, value|
   #       puts "> #{key} - #{value}"
@@ -1214,15 +1265,15 @@ class Sketchup::Model
   # @example
   #   model = Sketchup.active_model
   #   # Save the model using the current SketchUp format
-  #   filename = File.join(ENV['HOME'], 'Desktop', 'mysketchup.skp')
-  #   status = model.save(filename)
+  #   path = File.join(ENV['HOME'], 'Desktop', 'mysketchup.skp')
+  #   status = model.save(path)
   #   # Save the model to the current file using the current SketchUp format
   #   status = model.save
   #   # Save the model to the current file in SketchUp 8 format
   #   status = model.save("", Sketchup::Model::VERSION_8)
   #   # Save the model in SketchUp 8 format
-  #   filename = File.join(ENV['Home'], 'Desktop', 'mysketchup_v8.skp')
-  #   status = model.save("filename", Sketchup::Model::VERSION_8)
+  #   path = File.join(ENV['Home'], 'Desktop', 'mysketchup_v8.skp')
+  #   status = model.save(path, Sketchup::Model::VERSION_8)
   #
   # @note A bug in SketchUp 2016 and older caused the +.skb+ backup file
   #   written during save to be empty. The +.skp+ file was however valid.
@@ -1234,19 +1285,19 @@ class Sketchup::Model
   #   will be saved to the file to which it is associated. It must have
   #   already been saved to a file.
   #
-  # @overload save(filename)
+  # @overload save(path)
   #
-  #   @param [String] filename
+  #   @param [String] path
   #     The name of the file to save.
   #     Starting with SketchUp 2014, this parameter is optional.
   #     If not provided or an empty string, model will be saved
   #     to the file to which it is associated. It must have
   #     already been saved to a file.
   #
-  # @overload save(filename, version)
+  # @overload save(path, version)
   #
-  #   @param [String] filename
-  #     The name of the file to save.
+  #   @param [String] path
+  #     The path of the file to save to.
   #     Starting with SketchUp 2014, this parameter is optional.
   #     If not provided or an empty string, model will be saved
   #     to the file to which it is associated. It must have
@@ -1267,7 +1318,8 @@ class Sketchup::Model
   #     Sketchup::Model::VERSION_2017,
   #     Sketchup::Model::VERSION_2018,
   #     Sketchup::Model::VERSION_2019,
-  #     Sketchup::Model::VERSION_2020
+  #     Sketchup::Model::VERSION_2020,
+  #     Sketchup::Model::VERSION_2021
   #
   # @return [Boolean] true if successful, false if unsuccessful
   #
@@ -1280,14 +1332,14 @@ class Sketchup::Model
   # @example
   #   model = Sketchup.active_model
   #   # Save copy of the model using the current SketchUp format
-  #   filename = File.join(ENV['Home'], 'Desktop', 'myModelCopy.skp')
-  #   status = model.save_copy(filename)
+  #   path = File.join(ENV['Home'], 'Desktop', 'myModelCopy.skp')
+  #   status = model.save_copy(path)
   #   # Save copy of the model in SketchUp 8 format
-  #   filename = File.join(ENV['Home'], 'Desktop', 'mysketchupcopy_v8.skp')
-  #   status = model.save_copy(filename, Sketchup::Model::VERSION_8)
+  #   path = File.join(ENV['Home'], 'Desktop', 'mysketchupcopy_v8.skp')
+  #   status = model.save_copy(path, Sketchup::Model::VERSION_8)
   #
-  # @param [String] filename
-  #   The name of the file to save the model copy.
+  # @param [String] path
+  #   The path of the file to save the model copy to.
   #
   # @param [Integer] version
   #   (SketchUp 2014+)
@@ -1304,12 +1356,13 @@ class Sketchup::Model
   #   Sketchup::Model::VERSION_2017,
   #   Sketchup::Model::VERSION_2018,
   #   Sketchup::Model::VERSION_2019,
-  #   Sketchup::Model::VERSION_2020
+  #   Sketchup::Model::VERSION_2020,
+  #   Sketchup::Model::VERSION_2021
   #
   # @return [Boolean] true if successful, false if unsuccessful
   #
   # @version SketchUp 2014
-  def save_copy(filename, version)
+  def save_copy(path, version)
   end
 
   # The save_thumbnail method is used to save a thumbnail image to a file.