From 21962ef589dc8f63df76e0167735875779d752c9 Mon Sep 17 00:00:00 2001
From: Marc Cataford <mcat@riseup.net>
Date: Wed, 24 Jul 2024 22:06:14 -0400
Subject: [PATCH] docs: ins/outs and usage in README, update action metadata

---
 README.md  | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 action.yml |  9 +++++----
 2 files changed, 59 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 3994e2f..189f5af 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,56 @@
 # push-status-to-discord-action
 
+## Overview
+
+Posts build statuses to Discord via webhooks. If a message ID is provided when invoking, the specified message will be edited instead of creating a new one, keeping reporting channels tidy.
+
+## Inputs & outputs
+
+```yaml
+inputs:
+  webhook-url:
+    description: "Discord webhook url messages should be sent to."
+    required: true
+  title:
+    description: "Discord message title."
+    default: "${{github.repository}} (Build #${{github.run_number}})"
+  status:
+    description: "Status to report."
+    required: true
+  variant:
+    # See main.py for pre-defined variants.
+    description: "Style to attach to the message element."
+    default: "info"
+  message-id:
+    description: "Message ID to post to. If specified, the message will be updated instead of creating a new one."
+
+outputs:
+  message-id:
+    description: "ID of the message created or edited."
+```
+
+## Usage
+
+Unless a `message-id` input is provided, new messages are created on every invocation. The message ID can be passed around between jobs using the `@actions/upload-artifact` and `@actions/download-artifact` actions:
+
+```yaml
+jobs:
+    job1:
+        - uses: https://forge.karnov.club/marc/push-status-to-discord@main
+          id: post-message
+        - run: echo "${{ steps.post-message.outputs.message-id }}" >> /tmp/some-file
+        - uses: @actions/upload-artifact
+          with:
+            path: /tmp/some-file
+            name: some-name
+    job2:
+        - uses: @actions/download-artifact
+          with:
+            path: /tmp
+            name: some-name
+        - run: echo "message-id=$(cat /tmp/some-file)" >> $GITHUB_OUTPUT
+          id: get-message-id
+        - uses: https://forge.karnov.club/marc/push-status-to-discord@main
+          with:
+            message-id: ${{ steps.get-message-id.outputs.message-id }}
+```
diff --git a/action.yml b/action.yml
index e8fa00f..de000d9 100644
--- a/action.yml
+++ b/action.yml
@@ -2,23 +2,24 @@ name: Post build status to Discord
 
 inputs:
   webhook-url:
-    description: "Discord webhook URL events should be sent to."
+    description: "Discord webhook url messages should be sent to."
     required: true
   title:
-    description: "Message title"
+    description: "Discord message title."
     default: "${{github.repository}} (Build #${{github.run_number}})"
   status:
     description: "Status to report."
     required: true
   variant:
+    # See main.py for pre-defined variants.
     description: "Style to attach to the message element."
     default: "info"
   message-id:
-    description: "Message ID to post to."
+    description: "Message ID to post to. If specified, the message will be updated instead of creating a new one."
 
 outputs:
   message-id:
-    description: "Id of the message created, for later edits."
+    description: "ID of the message created or edited."
 
 runs:
   using: "docker"