social_stream-base 0.10.8 → 0.10.9

data/app/assets/stylesheets/base.css.scss

@@ -132,7 +132,7 @@ div.chzn-container ul.chzn-choices li.search-field input{ cursor:pointer;}
 
 /********* Menu header SECTION ************/
 .menu_list ul{list-style-type:none;}
-.menu_list li{display: inline;padding-right: 2px; padding-left: 2px; }
+.menu_list li{display: inline;padding-right: 2px; padding-left: 2px; vertical-align: top; }
 .line{  display:block;  margin:10px 2px 10px 10px;}
 
 /*************MENU ICON SECTION**********/

data/app/models/activity.rb

@@ -317,7 +317,7 @@ class Activity < ActiveRecord::Base
     receiver_name= receiver.name.truncate(30, :separator => ' ')
     case verb 
       when 'like'
-        if direct_object.is_a? Actor or direct_object.respond_to? :actor
+        if direct_object.acts_as_actor?
           I18n.t('notification.fan', 
                 :sender => sender_name,
                 :whose => I18n.t('notification.whose.'+ receiver.subject.class.to_s.underscore,

data/app/models/actor.rb

@@ -207,16 +207,25 @@ class Actor < ActiveRecord::Base
     Relation::Reject.of(self)
   end
  
-  # All the {Actor actors} this one has relation with
+  # All the {Actor Actors} this one has ties with:
+  # 
+  #   actor.contact_actors #=> array of actors that sent and receive ties from actor
   #
-  # Options:
-  # * type: Filter by the class of the contacts.
-  # * direction: sent or received
-  # * relations: Restrict the relations of considered ties. In the case of both directions,
-  #   only relations belonging to {Actor} are valid. It defaults to relations of
-  #   {Relation::Custom custom} and {Relation::Public public} types
-  # * include_self: False by default, don't include this actor as subject even they have ties with themselves.
-  # * load_subjects: True by default, make the queries for eager loading of contacts
+  #
+  #
+  # There are several options available to refine the query:
+  # type:: Filter by the class of the contacts ({User}, {Group}, etc.)
+  #          actor.contact_actors(:type => :user) #=> array of user actors. Exclude groups, etc.
+  #
+  # direction:: +:sent+ leaves only the actors this one has ties to. +:received+ gets
+  #             the actors sending ties to this actor, whether this actor added them or not
+  #               actor.contact_actors(:direction => :sent) #=> all the receivers of ties from actor
+  # relations:: Restrict to ties made up with +relations+. In the case of both directions,
+  #             only relations belonging to {Actor} are considered.
+  #             It defaults to actor's {Relation::Custom custom relations}
+  #               actor.contact_actors(:relations => [2]) #=> actors tied with relation #2
+  # include_self:: False by default, do not include this actor even they have ties with themselves.
+  # load_subjects:: True by default, make the queries for {http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#label-Eager+loading+of+associations eager loading} of {SocialStream::Models::Subject Subject}
   #
   def contact_actors(options = {})
     subject_types   = Array(options[:type] || self.class.subtypes)
@@ -231,14 +240,19 @@ class Actor < ActiveRecord::Base
       as = as.includes(subject_types)
     end
     
-    # Make another query for getting the actors in the other way
+    # A blank :direction means reciprocate contacts, there must be ties in both directions
+    #
+    # This is achieved by getting the id of all the contacts that are sending ties
+    # Then, we filter the sent contacts query to only those contacts
     if options[:direction].blank?
       rcv_opts = options.dup
       rcv_opts[:direction] = :received
       rcv_opts[:load_subjects] = false
 
+      # Get the id of actors that are sending to this one
       sender_ids = contact_actors(rcv_opts).map(&:id)
 
+      # Filter the sent query with these ids
       as = as.where(:id => sender_ids)
 
       options[:direction] = :sent

data/app/views/layouts/application.html.erb

@@ -7,6 +7,7 @@
     <meta name="keywords" content="<%= t('profile.tags.default') %><%= yield(:keywords) %>" >
     <meta name="description" content= "<%= yield(:description).empty? ? t('frontpage.main_title') : yield(:description) %>" >
     <meta name="generator" content="SocialStream" />
+    <meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no" />
 
     <%= stylesheet_link_tag    "application" %>
     <%= javascript_include_tag "application" %>

data/lib/social_stream/base/version.rb

@@ -1,5 +1,5 @@
 module SocialStream
   module Base
-    VERSION = "0.10.8".freeze
+    VERSION = "0.10.9".freeze
   end
 end

metadata

@@ -1,478 +1,336 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: social_stream-base
-version: !ruby/object:Gem::Version 
-  hash: 39
+version: !ruby/object:Gem::Version
+  version: 0.10.9
   prerelease: 
-  segments: 
-  - 0
-  - 10
-  - 8
-  version: 0.10.8
 platform: ruby
-authors: 
+authors:
 - GING - DIT - UPM
 - CISE - ESPOL
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-12-13 00:00:00 +01:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-12-16 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rails
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &77731060 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 3
-        - 1
-        - 0
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 3.1.0
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: ancestry
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *77731060
+- !ruby/object:Gem::Dependency
+  name: ancestry
+  requirement: &77730810 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 25
-        segments: 
-        - 1
-        - 2
-        - 3
+      - !ruby/object:Gem::Version
         version: 1.2.3
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: foreigner
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *77730810
+- !ruby/object:Gem::Dependency
+  name: foreigner
+  requirement: &77730580 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 17
-        segments: 
-        - 1
-        - 1
-        - 1
+      - !ruby/object:Gem::Version
         version: 1.1.1
   type: :runtime
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: devise
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: *77730580
+- !ruby/object:Gem::Dependency
+  name: devise
+  requirement: &77730350 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 13
-        segments: 
-        - 1
-        - 4
-        - 5
+      - !ruby/object:Gem::Version
         version: 1.4.5
   type: :runtime
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: inherited_resources
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  version_requirements: *77730350
+- !ruby/object:Gem::Dependency
+  name: inherited_resources
+  requirement: &77730120 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 27
-        segments: 
-        - 1
-        - 3
-        - 0
+      - !ruby/object:Gem::Version
         version: 1.3.0
   type: :runtime
-  version_requirements: *id005
-- !ruby/object:Gem::Dependency 
-  name: stringex
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  version_requirements: *77730120
+- !ruby/object:Gem::Dependency
+  name: stringex
+  requirement: &77729890 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 27
-        segments: 
-        - 1
-        - 3
-        - 0
+      - !ruby/object:Gem::Version
         version: 1.3.0
   type: :runtime
-  version_requirements: *id006
-- !ruby/object:Gem::Dependency 
-  name: avatars_for_rails
   prerelease: false
-  requirement: &id007 !ruby/object:Gem::Requirement 
+  version_requirements: *77729890
+- !ruby/object:Gem::Dependency
+  name: avatars_for_rails
+  requirement: &77729660 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 23
-        segments: 
-        - 0
-        - 2
-        - 0
+      - !ruby/object:Gem::Version
         version: 0.2.0
   type: :runtime
-  version_requirements: *id007
-- !ruby/object:Gem::Dependency 
-  name: jquery-rails
   prerelease: false
-  requirement: &id008 !ruby/object:Gem::Requirement 
+  version_requirements: *77729660
+- !ruby/object:Gem::Dependency
+  name: jquery-rails
+  requirement: &77729430 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 5
-        segments: 
-        - 1
-        - 0
-        - 9
+      - !ruby/object:Gem::Version
         version: 1.0.9
   type: :runtime
-  version_requirements: *id008
-- !ruby/object:Gem::Dependency 
-  name: cancan
   prerelease: false
-  requirement: &id009 !ruby/object:Gem::Requirement 
+  version_requirements: *77729430
+- !ruby/object:Gem::Dependency
+  name: cancan
+  requirement: &77729200 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 7
-        segments: 
-        - 1
-        - 6
-        - 4
+      - !ruby/object:Gem::Version
         version: 1.6.4
   type: :runtime
-  version_requirements: *id009
-- !ruby/object:Gem::Dependency 
-  name: kaminari
   prerelease: false
-  requirement: &id010 !ruby/object:Gem::Requirement 
+  version_requirements: *77729200
+- !ruby/object:Gem::Dependency
+  name: kaminari
+  requirement: &77728970 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 39
-        segments: 
-        - 0
-        - 12
-        - 4
+      - !ruby/object:Gem::Version
         version: 0.12.4
   type: :runtime
-  version_requirements: *id010
-- !ruby/object:Gem::Dependency 
-  name: omniauth
   prerelease: false
-  requirement: &id011 !ruby/object:Gem::Requirement 
+  version_requirements: *77728970
+- !ruby/object:Gem::Dependency
+  name: omniauth
+  requirement: &77762940 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 27
-        segments: 
-        - 0
-        - 2
-        - 6
+      - !ruby/object:Gem::Version
         version: 0.2.6
   type: :runtime
-  version_requirements: *id011
-- !ruby/object:Gem::Dependency 
-  name: mailboxer
   prerelease: false
-  requirement: &id012 !ruby/object:Gem::Requirement 
+  version_requirements: *77762940
+- !ruby/object:Gem::Dependency
+  name: mailboxer
+  requirement: &77762710 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        - 5
-        - 4
+      - !ruby/object:Gem::Version
         version: 0.5.4
   type: :runtime
-  version_requirements: *id012
-- !ruby/object:Gem::Dependency 
-  name: acts-as-taggable-on
   prerelease: false
-  requirement: &id013 !ruby/object:Gem::Requirement 
+  version_requirements: *77762710
+- !ruby/object:Gem::Dependency
+  name: acts-as-taggable-on
+  requirement: &77762480 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 2
-        - 0
-        - 6
+      - !ruby/object:Gem::Version
         version: 2.0.6
   type: :runtime
-  version_requirements: *id013
-- !ruby/object:Gem::Dependency 
-  name: formtastic
   prerelease: false
-  requirement: &id014 !ruby/object:Gem::Requirement 
+  version_requirements: *77762480
+- !ruby/object:Gem::Dependency
+  name: formtastic
+  requirement: &77762250 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 25
-        segments: 
-        - 1
-        - 2
-        - 3
+      - !ruby/object:Gem::Version
         version: 1.2.3
   type: :runtime
-  version_requirements: *id014
-- !ruby/object:Gem::Dependency 
-  name: simple-navigation
   prerelease: false
-  requirement: &id015 !ruby/object:Gem::Requirement 
+  version_requirements: *77762250
+- !ruby/object:Gem::Dependency
+  name: simple-navigation
+  requirement: &77762060 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id015
-- !ruby/object:Gem::Dependency 
-  name: resque
   prerelease: false
-  requirement: &id016 !ruby/object:Gem::Requirement 
+  version_requirements: *77762060
+- !ruby/object:Gem::Dependency
+  name: resque
+  requirement: &77761790 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 91
-        segments: 
-        - 1
-        - 19
-        - 0
+      - !ruby/object:Gem::Version
         version: 1.19.0
   type: :runtime
-  version_requirements: *id016
-- !ruby/object:Gem::Dependency 
-  name: modernizr-rails
   prerelease: false
-  requirement: &id017 !ruby/object:Gem::Requirement 
+  version_requirements: *77761790
+- !ruby/object:Gem::Dependency
+  name: modernizr-rails
+  requirement: &77761540 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 2
-        - 0
-        - 6
+      - !ruby/object:Gem::Version
         version: 2.0.6
   type: :runtime
-  version_requirements: *id017
-- !ruby/object:Gem::Dependency 
-  name: thinking-sphinx
   prerelease: false
-  requirement: &id018 !ruby/object:Gem::Requirement 
+  version_requirements: *77761540
+- !ruby/object:Gem::Dependency
+  name: thinking-sphinx
+  requirement: &77761310 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 31
-        segments: 
-        - 2
-        - 0
-        - 8
+      - !ruby/object:Gem::Version
         version: 2.0.8
   type: :runtime
-  version_requirements: *id018
-- !ruby/object:Gem::Dependency 
-  name: sass-rails
   prerelease: false
-  requirement: &id019 !ruby/object:Gem::Requirement 
+  version_requirements: *77761310
+- !ruby/object:Gem::Dependency
+  name: sass-rails
+  requirement: &77761080 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 3
-        - 1
-        - 0
+      - !ruby/object:Gem::Version
         version: 3.1.0
   type: :runtime
-  version_requirements: *id019
-- !ruby/object:Gem::Dependency 
-  name: rails_autolink
   prerelease: false
-  requirement: &id020 !ruby/object:Gem::Requirement 
+  version_requirements: *77761080
+- !ruby/object:Gem::Dependency
+  name: rails_autolink
+  requirement: &77760850 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 31
-        segments: 
-        - 1
-        - 0
-        - 4
+      - !ruby/object:Gem::Version
         version: 1.0.4
   type: :runtime
-  version_requirements: *id020
-- !ruby/object:Gem::Dependency 
-  name: capybara
   prerelease: false
-  requirement: &id021 !ruby/object:Gem::Requirement 
+  version_requirements: *77760850
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: &77760620 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 1
-        segments: 
-        - 0
-        - 3
-        - 9
+      - !ruby/object:Gem::Version
         version: 0.3.9
   type: :development
-  version_requirements: *id021
-- !ruby/object:Gem::Dependency 
-  name: sqlite3-ruby
   prerelease: false
-  requirement: &id022 !ruby/object:Gem::Requirement 
+  version_requirements: *77760620
+- !ruby/object:Gem::Dependency
+  name: sqlite3-ruby
+  requirement: &77760430 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id022
-- !ruby/object:Gem::Dependency 
-  name: ruby-debug
   prerelease: false
-  requirement: &id023 !ruby/object:Gem::Requirement 
+  version_requirements: *77760430
+- !ruby/object:Gem::Dependency
+  name: ruby-debug19
+  requirement: &77760190 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id023
-- !ruby/object:Gem::Dependency 
-  name: rspec-rails
   prerelease: false
-  requirement: &id024 !ruby/object:Gem::Requirement 
+  version_requirements: *77760190
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: &77759940 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 21
-        segments: 
-        - 2
-        - 6
-        - 1
+      - !ruby/object:Gem::Version
         version: 2.6.1
   type: :development
-  version_requirements: *id024
-- !ruby/object:Gem::Dependency 
-  name: factory_girl
   prerelease: false
-  requirement: &id025 !ruby/object:Gem::Requirement 
+  version_requirements: *77759940
+- !ruby/object:Gem::Dependency
+  name: factory_girl
+  requirement: &77759690 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 31
-        segments: 
-        - 1
-        - 3
-        - 2
+      - !ruby/object:Gem::Version
         version: 1.3.2
   type: :development
-  version_requirements: *id025
-- !ruby/object:Gem::Dependency 
-  name: forgery
   prerelease: false
-  requirement: &id026 !ruby/object:Gem::Requirement 
+  version_requirements: *77759690
+- !ruby/object:Gem::Dependency
+  name: forgery
+  requirement: &77759460 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 11
-        segments: 
-        - 0
-        - 4
-        - 2
+      - !ruby/object:Gem::Version
         version: 0.4.2
   type: :development
-  version_requirements: *id026
-- !ruby/object:Gem::Dependency 
-  name: ci_reporter
   prerelease: false
-  requirement: &id027 !ruby/object:Gem::Requirement 
+  version_requirements: *77759460
+- !ruby/object:Gem::Dependency
+  name: ci_reporter
+  requirement: &77759230 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 7
-        segments: 
-        - 1
-        - 6
-        - 4
+      - !ruby/object:Gem::Version
         version: 1.6.4
   type: :development
-  version_requirements: *id027
-- !ruby/object:Gem::Dependency 
-  name: nifty-generators
   prerelease: false
-  requirement: &id028 !ruby/object:Gem::Requirement 
+  version_requirements: *77759230
+- !ruby/object:Gem::Dependency
+  name: nifty-generators
+  requirement: &77759000 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 5
-        segments: 
-        - 0
-        - 4
-        - 5
+      - !ruby/object:Gem::Version
         version: 0.4.5
   type: :development
-  version_requirements: *id028
-description: |-
-  Social Stream is a Ruby on Rails engine providing your application with social networking features and activity streams.
-  
-  This gem packages the basic functionality, along with basic actors (user, group) and activity objects (post and comments)
+  prerelease: false
+  version_requirements: *77759000
+description: ! 'Social Stream is a Ruby on Rails engine providing your application
+  with social networking features and activity streams.
+
+
+  This gem packages the basic functionality, along with basic actors (user, group)
+  and activity objects (post and comments)'
 email: 
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - .rspec
 - .yardopts
@@ -1093,39 +951,29 @@ files:
 - vendor/assets/stylesheets/smoothness/jquery-ui-1.7.3.custom.css
 - vendor/assets/stylesheets/smoothness/jquery-ui-1.8.4.custom.css
 - vendor/assets/stylesheets/tipsy.css
-has_rdoc: true
 homepage: http://social-stream.dit.upm.es/
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.12
 signing_key: 
 specification_version: 3
 summary: Basic features for Social Stream, the core for building social network websites
 test_files: []
-
+has_rdoc: