Clarifying usage of commit_id in comment example

tomasbjerre · tomasbjerre · commit 3c3b8f031833 · 2016-03-14T16:48:09.000+01:00
* I interpreted it as if the example was showing how to make a commit comment on a commit in the PR. This makes it clearer that its a review comment on the unified diff.
diff --git a/content/v3/pulls/comments.md b/content/v3/pulls/comments.md
@@ -62,10 +62,12 @@ Name | Type | Description
 Name | Type | Description
 -----|------|--------------
 `body`|`string` | **Required**. The text of the comment
-`commit_id`|`string` | **Required**. The SHA of the commit to comment on.
+`commit_id`|`string` | **Required**. The SHA of the latest commit of the pull request to comment on.
 `path`|`string` | **Required**. The relative path of the file to comment on.
 `position`|`integer` | **Required**. The line index in the diff to comment on.
 
+Note: When passing the `commit_id`, use the SHA of the latest commit in the pull request or your comment may appear as "outdated" if the specified `position` has been modified in a subsequent commit.
+
 
 #### Example
 
