API: help page and comment

doc/api/merge_requests.md

+## List merge requests
+
+Get all MR for this project.
+
+```
+GET /:id/merge_requests
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
+
+```json
+[
+    {
+        "id":1,
+        "target_branch":"master",
+        "source_branch":"test1",
+        "project_id":3,
+        "title":"test1",
+        "closed":true,
+        "merged":false,
+        "author":{
+            "id":1,
+            "email":"admin@local.host",
+            "name":"Administrator",
+            "blocked":false,
+            "created_at":"2012-04-29T08:46:00Z"
+        },
+        "assignee":{
+            "id":1,
+            "email":"admin@local.host",
+            "name":"Administrator",
+            "blocked":false,
+            "created_at":"2012-04-29T08:46:00Z"
+        }
+    }
+]
+```
+
+## Show MR
+
+Show information about MR.
+
+```
+GET /:id/merge_request/:merge_request_id
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
++ `merge_request_id` (required) - The ID of MR
+
+```json
+{
+    "id":1,
+    "target_branch":"master",
+    "source_branch":"test1",
+    "project_id":3,
+    "title":"test1",
+    "closed":true,
+    "merged":false,
+    "author":{
+        "id":1,
+        "email":"admin@local.host",
+        "name":"Administrator",
+        "blocked":false,
+        "created_at":"2012-04-29T08:46:00Z"
+    },
+    "assignee":{
+        "id":1,
+        "email":"admin@local.host",
+        "name":"Administrator",
+        "blocked":false,
+        "created_at":"2012-04-29T08:46:00Z"
+    }
+}
+```
+
+
+## Create MR
+
+Create MR.
+
+```
+POST /:id/merge_requests
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
++ `source_branch` (required) - The source branch
++ `target_branch` (required) - The target branch
++ `assignee_id`              - Assignee user ID
++ `title` (required)         - Title of MR
+
+```json
+{
+    "id":1,
+    "target_branch":"master",
+    "source_branch":"test1",
+    "project_id":3,
+    "title":"test1",
+    "closed":true,
+    "merged":false,
+    "author":{
+        "id":1,
+        "email":"admin@local.host",
+        "name":"Administrator",
+        "blocked":false,
+        "created_at":"2012-04-29T08:46:00Z"
+    },
+    "assignee":{
+        "id":1,
+        "email":"admin@local.host",
+        "name":"Administrator",
+        "blocked":false,
+        "created_at":"2012-04-29T08:46:00Z"
+    }
+}
+```
+
+## Update MR
+
+Update MR. You can change branches, title, or even close the MR.
+
+```
+PUT /:id/merge_request/:merge_request_id
+```
+
+Parameters:
+
++ `id` (required)               - The ID or code name of a project
++ `merge_request_id` (required) - ID of MR
++ `source_branch`               - The source branch
++ `target_branch`               - The target branch
++ `assignee_id`                 - Assignee user ID
++ `title`                       - Title of MR
++ `closed`                      - Status of MR. true - closed
+
+
+```json
+{
+    "id":1,
+    "target_branch":"master",
+    "source_branch":"test1",
+    "project_id":3,
+    "title":"test1",
+    "closed":true,
+    "merged":false,
+    "author":{
+        "id":1,
+        "email":"admin@local.host",
+        "name":"Administrator",
+        "blocked":false,
+        "created_at":"2012-04-29T08:46:00Z"
+    },
+    "assignee":{
+        "id":1,
+        "email":"admin@local.host",
+        "name":"Administrator",
+        "blocked":false,
+        "created_at":"2012-04-29T08:46:00Z"
+    }
+}
+```
+## Post comment to MR
+
+Post comment to MR
+
+```
+POST /:id/merge_request/:merge_request_id/comments
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
++ `merge_request_id` (required) - ID of MR
++ `note` (required) - Text of comment
+
+Will return created note with status `201 Created` on success, or `404 Not found` on fail.
+
+```json
+{
+    "author":{
+        "id":1,
+        "email":"admin@local.host",
+        "name":"Administrator",
+        "blocked":false,
+        "created_at":"2012-04-29T08:46:00Z"
+    },
+    "note":"text1"
+}
+```

lib/api/merge_requests.rb

@@ -4,14 +4,30 @@ module Gitlab
     before { authenticate! }
 
     resource :projects do
-      #list
+      
+      # List merge requests
+      # 
+      # Parameters:
+      #   id (required) - The ID or code name of a project
+      #
+      # Example:
+      #   GET /:id/merge_requests
+      #
       get ":id/merge_requests" do
         authorize! :read_merge_request, user_project
         
-        present user_project.merge_requests, with: Entities::MergeRequest
+        present paginate(user_project.merge_requests), with: Entities::MergeRequest
       end
       
-      #show
+      # Show MR
+      # 
+      # Parameters:
+      #   id (required)               - The ID or code name of a project
+      #   merge_request_id (required) - The ID of MR
+      # 
+      # Example:
+      #   GET /:id/merge_request/:merge_request_id
+      #
       get ":id/merge_request/:merge_request_id" do
         merge_request = user_project.merge_requests.find(params[:merge_request_id])
         
@@ -20,7 +36,19 @@ module Gitlab
         present merge_request, with: Entities::MergeRequest
       end
 
-      #create merge_request
+      # Create MR
+      #
+      # Parameters:
+      #
+      #   id (required)            - The ID or code name of a project
+      #   source_branch (required) - The source branch
+      #   target_branch (required) - The target branch
+      #   assignee_id              - Assignee user ID
+      #   title (required)         - Title of MR
+      # 
+      # Example:
+      #   POST /:id/merge_requests
+      #
       post ":id/merge_requests" do
         attrs = attributes_for_keys [:source_branch, :target_branch, :assignee_id, :title]
         merge_request = user_project.merge_requests.new(attrs)
@@ -36,7 +64,19 @@ module Gitlab
         end
       end
 
-      #update merge_request
+      # Update MR
+      #
+      # Parameters:
+      #   id (required)               - The ID or code name of a project
+      #   merge_request_id (required) - ID of MR
+      #   source_branch               - The source branch
+      #   target_branch               - The target branch
+      #   assignee_id                 - Assignee user ID
+      #   title                       - Title of MR
+      #   closed                      - Status of MR. true - closed
+      # Example:
+      #   PUT /:id/merge_request/:merge_request_id
+      #
       put ":id/merge_request/:merge_request_id" do
         attrs = attributes_for_keys [:source_branch, :target_branch, :assignee_id, :title, :closed]
         merge_request = user_project.merge_requests.find(params[:merge_request_id])
@@ -52,7 +92,15 @@ module Gitlab
         end
       end
 
-      #post comment to merge request
+      # Post comment to merge request
+      #
+      # Parameters:
+      #   id (required) - The ID or code name of a project
+      #   merge_request_id (required) - ID of MR
+      #   note (required) - Text of comment
+      # Examples: 
+      #   POST /:id/merge_request/:merge_request_id/comments
+      #
       post ":id/merge_request/:merge_request_id/comments" do
         merge_request = user_project.merge_requests.find(params[:merge_request_id])
         note = merge_request.notes.new(note: params[:note], project_id: user_project.id)