Improve API calls for comments

docs/api-json-rpc.markdown

@@ -440,6 +440,18 @@ Response example:
 - Result on success: **board properties**
 - Result on failure: **null**
 
+Request example:
+
+```json
+
+```
+
+Response example:
+
+```json
+
+```
+
 ### getColumns
 
 - Purpose: **Get all columns information for a given project**
@@ -447,6 +459,18 @@ Response example:
 - Result on success: **columns properties**
 - Result on failure: **null**
 
+Request example:
+
+```json
+
+```
+
+Response example:
+
+```json
+
+```
+
 ### moveColumnUp
 
 - Purpose: **Move up the column position**
@@ -454,6 +478,18 @@ Response example:
 - Result on success: **true**
 - Result on failure: **false**
 
+Request example:
+
+```json
+
+```
+
+Response example:
+
+```json
+
+```
+
 ### moveColumnDown
 
 - Purpose: **Move down the column position**
@@ -461,6 +497,18 @@ Response example:
 - Result on success: **true**
 - Result on failure: **false**
 
+Request example:
+
+```json
+
+```
+
+Response example:
+
+```json
+
+```
+
 ### updateColumn
 
 - Purpose: **Update column properties**
@@ -468,6 +516,18 @@ Response example:
 - Result on success: **true**
 - Result on failure: **false**
 
+Request example:
+
+```json
+
+```
+
+Response example:
+
+```json
+
+```
+
 ### addColumn
 
 - Purpose: **Add a new column**
@@ -475,6 +535,18 @@ Response example:
 - Result on success: **true**
 - Result on failure: **false**
 
+Request example:
+
+```json
+
+```
+
+Response example:
+
+```json
+
+```
+
 ### removeColumn
 
 - Purpose: **Remove a column**
@@ -482,6 +554,18 @@ Response example:
 - Result on success: **true**
 - Result on failure: **false**
 
+Request example:
+
+```json
+
+```
+
+Response example:
+
+```json
+
+```
+
 ### getAllowedUsers
 
 - Purpose: **Get allowed users for a given project**
@@ -489,6 +573,18 @@ Response example:
 - Result on success: Key/value pair of user_id and username
 - Result on failure: **false**
 
+Request example:
+
+```json
+
+```
+
+Response example:
+
+```json
+
+```
+
 ### revokeUser
 
 - Purpose: **Revoke user access for a given project**
@@ -496,6 +592,18 @@ Response example:
 - Result on success: **true**
 - Result on failure: **false**
 
+Request example:
+
+```json
+
+```
+
+Response example:
+
+```json
+
+```
+
 ### allowUser
 
 - Purpose: **Grant user access for a given project**
@@ -503,7 +611,17 @@ Response example:
 - Result on success: **true**
 - Result on failure: **false**
 
+Request example:
 
+```json
+
+```
+
+Response example:
+
+```json
+
+```
 
 
 ### createTask
@@ -853,6 +971,18 @@ Response example:
 - Result on success: **true**
 - Result on failure: **false**
 
+Request example:
+
+```json
+
+```
+
+Response example:
+
+```json
+
+```
+
 ### getUser
 
 - Purpose: **Get user information**
@@ -860,6 +990,18 @@ Response example:
 - Result on success: **user properties**
 - Result on failure: **null**
 
+Request example:
+
+```json
+
+```
+
+Response example:
+
+```json
+
+```
+
 ### getAllUsers
 
 - Purpose: **Get all available users**
@@ -867,6 +1009,18 @@ Response example:
 - Result on success: **List of users**
 - Result on failure: **false**
 
+Request example:
+
+```json
+
+```
+
+Response example:
+
+```json
+
+```
+
 ### updateUser
 
 - Purpose: **Update a user**
@@ -874,6 +1028,18 @@ Response example:
 - Result on success: **true**
 - Result on failure: **false**
 
+Request example:
+
+```json
+
+```
+
+Response example:
+
+```json
+
+```
+
 ### removeUser
 
 - Purpose: **Remove a user**
@@ -881,7 +1047,17 @@ Response example:
 - Result on success: **true**
 - Result on failure: **false**
 
+Request example:
 
+```json
+
+```
+
+Response example:
+
+```json
+
+```
 
 
 ### createCategory
@@ -1058,39 +1234,182 @@ Response example:
 ### createComment
 
 - Purpose: **Create a new comment**
-- Parameters: Key/value pair composed of the **task_id** (integer), **user_id** (integer), **comment** (string)
+- Parameters:
+    - **task_id** (integer, required)
+    - **user_id** (integer, required)
+    - **content** Markdown content (string, required)
 - Result on success: **true**
 - Result on failure: **false**
 
+Request example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "createComment",
+    "id": 1580417921,
+    "params": {
+        "task_id": 1,
+        "user_id": 1,
+        "content": "Comment #1"
+    }
+}
+```
+
+Response example:
+
+```json
+
+    "jsonrpc": "2.0",
+    "id": 1580417921,
+    "result": true
+}
+```
+
 ### getComment
 
 - Purpose: **Get comment information**
-- Parameters: **comment_id** (integer)
+- Parameters:
+    - **comment_id** (integer, required)
 - Result on success: **comment properties**
 - Result on failure: **null**
 
+Request example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "getComment",
+    "id": 867839500,
+    "params": {
+        "comment_id": 1
+    }
+}
+```
+
+Response example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "id": 867839500,
+    "result": {
+        "id": "1",
+        "task_id": "1",
+        "user_id": "1",
+        "date": "1410881970",
+        "comment": "Comment #1",
+        "username": "admin",
+        "name": null
+    }
+}
+```
+
 ### getAllComments
 
 - Purpose: **Get all available comments**
-- Parameters: **none**
+- Parameters:
+    - **task_id** (integer, required)
 - Result on success: **List of comments**
 - Result on failure: **false**
 
+Request example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "getAllComments",
+    "id": 148484683,
+    "params": {
+        "task_id": 1
+    }
+}
+```
+
+Response example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "id": 148484683,
+    "result": [
+        {
+            "id": "1",
+            "date": "1410882272",
+            "task_id": "1",
+            "user_id": "1",
+            "comment": "Comment #1",
+            "username": "admin",
+            "name": null
+        },
+        ...
+    ]
+}
+```
+
 ### updateComment
 
 - Purpose: **Update a comment**
-- Parameters: Key/value pair composed of the **id** (integer), **task_id** (integer), **user_id** (integer), **comment** (string)
+- Parameters:
+    - **id** (integer, required)
+    - **content** Markdown content (string, required)
 - Result on success: **true**
 - Result on failure: **false**
 
+Request example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "updateComment",
+    "id": 496470023,
+    "params": {
+        "id": 1,
+        "content": "Comment #1 updated"
+    }
+}
+```
+
+Response example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "id": 1493368950,
+    "result": true
+}
+```
+
 ### removeComment
 
 - Purpose: **Remove a comment**
-- Parameters: **comment_id** (integer)
+- Parameters:
+    - **comment_id** (integer, required)
 - Result on success: **true**
 - Result on failure: **false**
 
+Request example:
 
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "removeComment",
+    "id": 328836871,
+    "params": {
+        "comment_id": 1
+    }
+}
+```
+
+Response example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "id": 328836871,
+    "result": true
+}
+```
 
 
 ### createSubtask