add some inline documentation

lib/open_project/github_integration/hook_handler.rb

@@ -1,7 +1,11 @@
 module OpenProject::GithubIntegration
   class HookHandler
+    # List of the github events we can handle.
     KNOWN_EVENTS = %w{ ping pull_request }
 
+    # A github webhook happened.
+    # We need to check validity of the data and send a Notification
+    # which we process in our NotificationHandler.
     def process(hook, environment, params, user)
       event_type = environment['HTTP_X_GITHUB_EVENT']
       event_delivery = environment['HTTP_X_GITHUB_DELIVERY']

lib/open_project/github_integration/notification_handlers.rb

@@ -1,9 +1,24 @@
 module OpenProject::GithubIntegration
+
+  ##
+  # Handles github-related notifications.
   module NotificationHandlers
-    def self.ping(payload)
-      puts "ping", payload
-    end
 
+    ##
+    # Handles a pull_request webhook notification.
+    # The payload looks similar to this:
+    # { user_id: <the id of the OpenProject user in whose name the webhook is processed>,
+    #   github_event: 'pull_request',
+    #   github_delivery: <randomly generated ID idenfitying a single github notification>,
+    # Have a look at the github documentation about the next keys:
+    # http://developer.github.com/v3/activity/events/types/#pullrequestevent
+    #   action: 'opened' | 'closed' | 'synchronize' | 'reopened',
+    #   number: <pull request number>,
+    #   pull_request: <details of the pull request>
+    # We observed the following keys to appear. However they are not documented by github
+    #   sender: <the github user who opened a pull request> (might not appear on closed, synchronized, or reopened - we habven't checked)
+    #   repo: <the repository in action>
+    # }
     def self.pull_request(payload)
       puts "pull_request", payload
     end