diff --git a/app/roles/account.rb b/app/roles/account.rb
index ede12b6..7596c83 100644
--- a/app/roles/account.rb
+++ b/app/roles/account.rb
@@ -1,3 +1,9 @@
+# == Account role
+#
+# Describe behaviour of User in application
+#
+# Used by User
+#
 module Account
   # Returns a string for use as a Gitolite user identifier
   #
diff --git a/app/roles/authority.rb b/app/roles/authority.rb
index e0796d5..5e0d61c 100644
--- a/app/roles/authority.rb
+++ b/app/roles/authority.rb
@@ -1,3 +1,9 @@
+# == Authority role
+#
+# Control access to project repository based on users role in team
+#
+# Used by Project
+#
 module Authority
   # Compatible with all access rights
   # Should be rewrited for new access rights
diff --git a/app/roles/git_host.rb b/app/roles/git_host.rb
index aa620f7..2410e0f 100644
--- a/app/roles/git_host.rb
+++ b/app/roles/git_host.rb
@@ -1,3 +1,9 @@
+# == GitHost role
+#
+# Provide a shortcut to Gitlab::Gitolite instance
+#
+# Used by Project, UsersProject
+#
 module GitHost
   def git_host
     Gitlab::Gitolite.new
diff --git a/app/roles/issue_commonality.rb b/app/roles/issue_commonality.rb
index 79831cd..3948ef1 100644
--- a/app/roles/issue_commonality.rb
+++ b/app/roles/issue_commonality.rb
@@ -1,4 +1,9 @@
+# == IssueCommonality role
+#
 # Contains common functionality shared between Issues and MergeRequests
+#
+# Used by Issue, MergeRequest
+#
 module IssueCommonality
   extend ActiveSupport::Concern
 
diff --git a/app/roles/namespaced_project.rb b/app/roles/namespaced_project.rb
index dbd533f..1c10c8f 100644
--- a/app/roles/namespaced_project.rb
+++ b/app/roles/namespaced_project.rb
@@ -1,3 +1,12 @@
+# == NamespacedProject role
+#
+# Provides extra functionality for Project related to namespaces like:
+#  - transfer project between namespaces
+#  - name, path including namespece
+#  - project owner based on namespace
+#
+# Used by Project
+#
 module NamespacedProject
   def transfer(new_namespace)
     Project.transaction do
diff --git a/app/roles/note_event.rb b/app/roles/note_event.rb
index db4ced0..8e311ea 100644
--- a/app/roles/note_event.rb
+++ b/app/roles/note_event.rb
@@ -1,3 +1,9 @@
+# == NoteEvent role
+#
+# Extends Event model functionality by providing extra methods related to comment events
+#
+# Used by Event
+#
 module NoteEvent
   def note_commit_id
     target.commit_id
diff --git a/app/roles/push_event.rb b/app/roles/push_event.rb
index 8ce71b5..ac9c38c 100644
--- a/app/roles/push_event.rb
+++ b/app/roles/push_event.rb
@@ -1,3 +1,9 @@
+# == PushEvent role
+#
+# Extends Event model functionality by providing extra methods related to push events
+#
+# Used by Event
+#
 module PushEvent
   def valid_push?
     data[:ref]
@@ -58,7 +64,7 @@ module PushEvent
     @commits ||= data[:commits].map { |commit| project.commit(commit[:id]) }.reverse
   end
 
-  def commits_count 
+  def commits_count
     data[:total_commits_count] || commits.count || 0
   end
 
@@ -88,7 +94,7 @@ module PushEvent
     nil
   end
 
-  def push_with_commits? 
+  def push_with_commits?
     md_ref? && commits.any? && parent_commit && last_commit
   rescue Grit::NoSuchPathError
     false
diff --git a/app/roles/push_observer.rb b/app/roles/push_observer.rb
index dd33b6e..42979f4 100644
--- a/app/roles/push_observer.rb
+++ b/app/roles/push_observer.rb
@@ -1,6 +1,11 @@
-# Includes methods for handling Git Push events
+# == PushObserver role
 #
+# Includes methods to be triggered on push to project repository.
+#
+#
+# Used by Project
 # Triggered by PostReceive job
+#
 module PushObserver
   # This method will be called after each post receive and only if the provided
   # user is present in GitLab.
diff --git a/app/roles/repository.rb b/app/roles/repository.rb
index 78190ca..8896569 100644
--- a/app/roles/repository.rb
+++ b/app/roles/repository.rb
@@ -1,3 +1,10 @@
+# == Repository role
+#
+# Provides access to git repository resources like commits, branches etc..
+# Allows you to manage repository via gitolite interface(git_host)
+#
+# Used by Project
+#
 module Repository
   include GitHost
 
diff --git a/app/roles/team.rb b/app/roles/team.rb
index a228e21..8e431fc 100644
--- a/app/roles/team.rb
+++ b/app/roles/team.rb
@@ -1,3 +1,12 @@
+# == Team role
+#
+# Provides functionality to manage project team
+#  - add user/users to project
+#  - update existing membership
+#  - remove users from project team
+#
+# Used by Project
+#
 module Team
   def team_member_by_name_or_email(name = nil, email = nil)
     user = users.where("name like ? or email like ?", name, email).first
diff --git a/app/roles/votes.rb b/app/roles/votes.rb
index 043a6fe..dfd751b 100644
--- a/app/roles/votes.rb
+++ b/app/roles/votes.rb
@@ -1,3 +1,10 @@
+# == Votes role
+#
+# Provides functionality to upvote/downvote entity
+# based on +1 and -1 notes
+#
+# Used for Issue and Merge Request
+#
 module Votes
   # Return the number of +1 comments (upvotes)
   def upvotes
--
libgit2 0.21.2