diff --git a/src/main/java/org/kohsuke/github/GHPullRequest.java b/src/main/java/org/kohsuke/github/GHPullRequest.java
index 4c397e93d2..015b6a3e68 100644
--- a/src/main/java/org/kohsuke/github/GHPullRequest.java
+++ b/src/main/java/org/kohsuke/github/GHPullRequest.java
@@ -388,9 +388,13 @@ public void refresh() throws IOException {
     }
 
     /**
-     * Retrieves all the files associated to this pull request.
+     * Retrieves all the files associated to this pull request. The paginated response returns 30 files per page by
+     * default.
      *
      * @return the paged iterable
+     *
+     * @see <a href="https://docs.github.com/en/rest/reference/pulls#list-pull-requests-files">List pull requests
+     *      files</a>
      */
     public PagedIterable<GHPullRequestFileDetail> listFiles() {
         return root.createRequest()
diff --git a/src/main/java/org/kohsuke/github/GHPullRequestFileDetail.java b/src/main/java/org/kohsuke/github/GHPullRequestFileDetail.java
index 908bd76800..358ea8c38c 100644
--- a/src/main/java/org/kohsuke/github/GHPullRequestFileDetail.java
+++ b/src/main/java/org/kohsuke/github/GHPullRequestFileDetail.java
@@ -30,6 +30,7 @@
  *
  * @author Julien Henry
  * @see GHPullRequest#listFiles() GHPullRequest#listFiles()
+ * @see <a href="https://docs.github.com/en/rest/reference/pulls#list-pull-requests-files">List pull requests files</a>
  */
 public class GHPullRequestFileDetail {
 
@@ -46,7 +47,10 @@ public class GHPullRequestFileDetail {
     String previous_filename;
 
     /**
-     * Gets sha.
+     * Gets sha of the file (not commit sha).
+     *
+     * @see <a href="https://docs.github.com/en/rest/reference/pulls#list-pull-requests-files">List pull requests
+     *      files</a>
      *
      * @return the sha
      */
@@ -64,7 +68,7 @@ public String getFilename() {
     }
 
     /**
-     * Gets status.
+     * Gets status (added/modified/deleted)
      *
      * @return the status
      */