Apply documentation suggestions from code review

Co-authored-by: Andrew Eisenberg <aeisenberg@github.com>

CHANGELOG.md

@@ -7,6 +7,8 @@
 
 ## 1.0.31 - 31 Jan 2022
 
+- Add `sarif-id` as an output for the `upload-sarif` and `analyze` actions. [#889](https://github.com/github/codeql-action/pull/889)
+- Add `ref` and `sha` inputs to the `analyze` action, which override the defaults provided by the GitHub Action context. [#889](https://github.com/github/codeql-action/pull/889)
 - Remove `experimental` message when using custom CodeQL packages. [#888](https://github.com/github/codeql-action/pull/888)
 - Add a better warning message stating that experimental features will be disabled if the workflow has been triggered by a pull request from a fork or the `security-events: write` permission is not present. [#882](https://github.com/github/codeql-action/pull/882)
 

analyze/action.yml

@@ -46,10 +46,10 @@ inputs:
     required: false
     default: ${{ github.workspace }}
   ref:
-    description: "The ref where results will be uploaded. If not provided, the Action will use the GITHUB_REF environment variable."
+    description: "The ref where results will be uploaded. If not provided, the Action will use the GITHUB_REF environment variable. If provided, the sha input must be provided as well."
     required: false
   sha:
-    description: "The hash of the HEAD of the ref where results will be uploaded. If not provided, the Action will use the GITHUB_SHA environment variable."
+    description: "The sha of the HEAD of the ref where results will be uploaded. If not provided, the Action will use the GITHUB_SHA environment variable. If provided, the ref input must be provided as well."
     required: false
   category:
     description: String used by Code Scanning for matching the analyses
@@ -70,7 +70,7 @@ outputs:
   db-locations:
     description: A map from language to absolute path for each database created by CodeQL.
   sarif-id:
-    description: The ID of the uploaded sarif file.
+    description: The ID of the uploaded SARIF file.
 runs:
   using: "node12"
   main: "../lib/analyze-action.js"

upload-sarif/action.yml

@@ -32,7 +32,7 @@ inputs:
     default: "false"
 outputs:
   sarif-id:
-    description: The ID of the uploaded sarif file.
+    description: The ID of the uploaded SARIF file.
 runs:
   using: 'node12'
   main: '../lib/upload-sarif-action.js'