lib/scrivito/user.rb in scrivito_sdk-0.66.0 vs lib/scrivito/user.rb in scrivito_sdk-0.70.0.rc1

@@ -20,13 +20,13 @@
       #
       # Defines a new user.
       #
       # @api public
       #
-      # @param [String] id the unique, unalterable id of the user.
+      # @param [String] id The unique, unalterable id of the user.
       #   The user id is used to associate the user with the corresponding CMS resources.
-      #   It will be persisted in the CMS.
+      #   It is persisted in the CMS.
       #
       # @raise [Scrivito::ScrivitoError] if id is blank
       # @raise [Scrivito::ScrivitoError] if id is more than 64 characters long
       #
       # @yieldparam [Scrivito::UserDefinition] user object to define rules on
@@ -36,25 +36,25 @@
       # @see Scrivito::UserDefinition#description
       # @see Scrivito::UserDefinition#restrict_obj_publish
       # @see Scrivito::UserDefinition#suggest_users
       #
       # @example
-      #   Scrivito::User.define('alice') do |user|
-      #     user.description { 'Alice Almighty' }
+      #   Scrivito::User.define('alice') do |user_definition|
+      #     user_definition.description { 'Alice Almighty' }
       #
-      #     user.can_always(:read, :workspace)
-      #     user.can_always(:write, :workspace)
-      #     user.can_always(:publish, :workspace, 'You can always publish workspaces.')
+      #     user_definition.can_always(:read, :workspace)
+      #     user_definition.can_always(:write, :workspace)
+      #     user_definition.can_always(:publish, :workspace, 'You can always publish workspaces.')
       #   end
       #
-      #   Scrivito::User.define('bob') do |user|
-      #     user.description('Bob Doe')
+      #   Scrivito::User.define('bob') do |user_definition|
+      #     user_definition.description('Bob Doe')
       #
-      #     user.can_never(:create, :workspace, 'You are not allowed to create workspaces.')
-      #     user.can_always(:read, :workspace)
+      #     user_definition.can_never(:create, :workspace, 'You are not allowed to create workspaces.')
+      #     user_definition.can_always(:read, :workspace)
       #
-      #     user.restrict_obj_publish(using: :_obj_class_name) do |obj_class_name|
+      #     user_definition.restrict_obj_publish(using: :_obj_class_name) do |obj_class_name|
       #       if obj_class_name == 'BlogPost'
       #         false
       #       else
       #         'You are not allowed to publish blog posts.'
       #       end
@@ -65,13 +65,20 @@
         assert_valid_id(id)
         define_user(id, &block)
       end
 
       #
-      # Returns an anonymous system user, who can always create workspaces, can always read, write,
-      # publish, delete and invite to any workspace.
+      # Returns an anonymous system user who can always create workspaces, can always read, write,
+      # publish, delete, and invite others to collaborate on any workspace.
+      # @example Check whether the user may publish a particular object:
+      #   Scrivito::User.system_user.can_publish?(Obj.root)
+      #   # => true
       #
+      # @example Get the notification messages for publishing restrictions. An empty array indicates that no restrictions exist.
+      #   Scrivito::User.system_user.restriction_messages_for(Obj.root)
+      #   # => []
+      #
       # @api public
       # @return [Scrivito::User] the system user
       #
       def system_user
         define_user { |user| user.is_admin! }
@@ -143,28 +150,28 @@
       membership = workspace.memberships[self]
       membership ? membership.role == 'owner' : false
     end
 
     #
-    # Verifies if the User is able to publish changes to a certain {BasicObj Obj}
+    # Checks whether the User may publish changes to a specific {Scrivito::BasicObj Obj}.
     #
     # @api public
-    # @param [BasicObj] obj the obj that should be published
-    # @return [Boolean] true if the user is allowed to publish otherwise false
+    # @param [BasicObj] obj the object to be published
+    # @return [Boolean] true if the user is allowed to publish the object, otherwise false
     #
     def can_publish?(obj)
       restriction_messages_for(obj).empty?
     end
 
     #
-    # Checks if the User is able to publish changes and returns the message
-    # specified in a {UserDefinition#restrict_obj_publish} callback if they are not
-    # If the user can publish the obj an empty array is returned
+    # Checks whether the User may publish changes to an {Scrivito::BasicObj Obj} and returns
+    # the message specified in a {UserDefinition#restrict_obj_publish} callback if they may not.
+    # If the user may publish the CMS object, an empty array is returned.
     #
     # @api public
-    # @param [BasicObj] obj the obj that should be published
-    # @return [Array<String>] Hints why the user can't publish
+    # @param [BasicObj] obj the object to be published
+    # @return [Array<String>] Hints on why the user cannot publish the object
     #
     def restriction_messages_for(obj)
       assert_restrictions_applicable(obj)
 
       return [] if can_always?(:publish, :workspace)
@@ -191,10 +198,10 @@
         user = self.class.find(input)
         user ? [user] : []
       end
     end
 
-    # Per convention only anonymous admin has a nil id.
+    # By convention, only the anonymous admin user has a +nil+ id.
     def system_user?
       id.nil?
     end
 
     private