scrivito_sdk.rb in scrivito_sdk-0.70.0.rc1

- old
+ new

@@ -2,11 +2,11 @@
 
 # @api public
 module Scrivito
   #
   # Configures the Scrivito SDK.
-  # The configuration keys +tenant+ and +api_key+ _must_ be provided.
+  # The +tenant+ and +api_key+ configuration keys _must_ be provided.
   #
   # @example
   #   Scrivito.configure do |config|
   #     config.tenant  = 'my-tenant-name'
   #     config.api_key = 'secret'
@@ -17,27 +17,27 @@
   def self.configure
     yield Configuration
   end
 
   #
-  # Configures which models Scrivito assumes as pages and widgets.
+  # Configures which models Scrivito regards as pages and widgets.
   #
   # @api public
   #
   # In order to display a page class selection dialog and a widget class selection dialog, Scrivito
-  # needs to know which page models and widget models are available. That models can be defined in
+  # needs to know which page models and widget models are available. These models can be defined in
   # the Rails application itself or in 3rd-party gems.
   #
-  # Scrivito will automatically assume all the classes descending from {Scrivito::BasicObj}, whose
-  # class names are ending with +Page+ are pages (e.g. +MyPage+, +HomePage+, +BlogPostPage+ etc.).
-  # It will also automatically assume all the classes descending from {Scrivito::BasicWidget}, whose
-  # class names are ending with +Widget+ are widgets (e.g. +TextWidget+, +ImageWdidget+ etc.).
+  # Scrivito assumes that all the classes descending from {Scrivito::BasicObj}, whose
+  # class names end with +Page+ are pages (e.g. +MyPage+, +HomePage+, +BlogPostPage+ etc.).
+  # It also assumes that all the classes descending from {Scrivito::BasicWidget}, whose
+  # class names end with +Widget+ are widgets (e.g. +TextWidget+, +ImageWdidget+ etc.).
   #
-  # Scrivito will recursively scan for such models in all directories from
+  # Scrivito recursively scans for such models in all directories from
   # {Scrivito::ModelLibrary#paths Scrivito.models.paths}, which is an array of strings.
-  # It by default includes the directory +app/models+ of the Rails application. For example it will
-  # find following page and widget models:
+  # By default, Scrivito includes the +app/models+ directory of the Rails application when searching
+  # for models. It will, for example, find the following page and widget models:
   #
   # +app/models/my_page.rb+
   #
   # +app/models/my_widget.rb+
   #
@@ -47,14 +47,14 @@
   #
   # +app/models/my_namespace/my_other_namespace/my_other_special_page.rb+
   #
   # +app/models/my_namespace/my_other_namespace/my_other_special_widget.rb+
   #
-  # Also {Scrivito::ModelLibrary#paths Scrivito.models.paths} will include all directories ending
-  # with +app/models+ of any available Rails engine, as long as that directory is included in the
-  # autoload paths of Rails (which is the default). For example it will find following page and
-  # widget models in an engine:
+  # Also, {Scrivito::ModelLibrary#paths Scrivito.models.paths} includes all +app/models+
+  # directories of any available Rails engine, provided that these directories are included in the
+  # autoload paths of Rails (which is the default). For example, it will find the following page
+  # and widget models in an engine:
   #
   # +/../some_engine/app/models/my_page.rb+
   #
   # +/../some_engine/app/models/my_widget.rb+
   #
@@ -65,43 +65,43 @@
   # +/../some_engine/app/models/my_namespace/my_other_namespace/my_other_special_page.rb+
   #
   # +/../some_engine/app/models/my_namespace/my_other_namespace/my_other_special_widget.rb+
   #
   # You can add custom directories to scan for models and register single page and widget models
-  # with {Scrivito::ModelLibrary#define Scrivito.models.define} (see examples below).
+  # using {Scrivito::ModelLibrary#define Scrivito.models.define} (see examples below).
   #
   # The loaded pages can be inspected with {Scrivito::ModelLibrary#pages Scrivito.models.pages},
-  # which will return a {Scrivito::ClassCollection} containing all available pages.
+  # which will return a {Scrivito::ClassCollection} containing the available pages.
   # The loaded widgets can be inspected with {Scrivito::ModelLibrary#widgets Scrivito.models.widgets},
-  # which will return a {Scrivito::ClassCollection} containing all available widgets.
+  # which will return a {Scrivito::ClassCollection} containing the available widgets.
   #
-  # The scan results are cached. If +Rails.application.config.cache_classes+ is +false+, then the
-  # cache will be cleared on every request. Otherwise the cache will be kept between the requests.
-  # You can clear the cache with {Scrivito::ModelLibrary#clear_cache Scrivito.models.clear_cache}.
+  # The scan results are cached. If +Rails.application.config.cache_classes+ is +false+, the
+  # cache is cleared on every request. Otherwise, the cache is kept between the requests.
+  # You can clear the cache using {Scrivito::ModelLibrary#clear_cache Scrivito.models.clear_cache}.
   #
-  # @example Register a custom path
+  # @example Register a custom path:
   #   Scrivito.models.define do
   #     paths << Rails.root + 'lib/special_models'
   #   end
   #
-  # @example Register pages and widgets with inconvenient names
+  # @example Register pages and widgets with unusual names:
   #   Scrivito.models.define do
   #     page 'MyCrazyPageModel'
   #     page 'MyOtherCrazyPageModel1', 'MyOtherCrazyPageModel2'
   #
   #     widget 'MyCrazyWidgetModel'
   #     widget 'MyOtherCrazyWidgetModel1', 'MyOtherCrazyWidgetModel2'
   #   end
   #
-  # @example Iterate over available pages
+  # @example Iterate over the available pages:
   #   Scrivito.models.pages.each do |page_class|
   #     puts page_class.name
   #   end
   #   #=> "MyPage"
   #   #=> "MyOtherPage"
   #   # ...
   #
-  # @example Iterate over available widgets
+  # @example Iterate over the available widgets:
   #   Scrivito.models.widgets.each do |widget_class|
   #     puts widget_class.name
   #   end
   #   #=> "MyWidget"
   #   #=> "MyOtherWidget"