From 7d8dad73128118abc8b1d797d3ad75b93ca8bcdc Mon Sep 17 00:00:00 2001
From: Paul Campbell <campbjpa@amazon.com>
Date: Fri, 20 Sep 2024 17:15:16 +0100
Subject: [PATCH] docs: add instructions in README

---
 README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 64 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 8347668..9974d4c 100644
--- a/README.md
+++ b/README.md
@@ -2,4 +2,67 @@
 
 Checks your source files for TODO and FIXME comments, where they don't have an open issue number.
 
-(Inspired by https://woodpecker-ci.org/plugins/TODO-Checker)
\ No newline at end of file
+A ForgeJo Action.
+
+(Inspired by https://woodpecker-ci.org/plugins/TODO-Checker)
+
+## Comments Format
+
+This Action only pays attention to comments in a particular format. e.g:
+
+```
+// TODO: (#19) This is the comment
+// FIXME (#29) This is the other comment
+# TODO (#19) This is the comment
+# FIXME: (#29) This is the other comment
+```
+
+These are all considered valid comments. Pick the format that fits your language or file best.
+
+Comments are found by matching them against this regular expression: `(#|//)\s*(TODO|FIXME)`
+
+i.e.: be a comment by starting with either '#' or '//', then the word `TODO` or `FIXME` in all caps.
+
+Once we have a line with such a comment we look for the Issue Number with: `\(#?(?P<ISSUE_NUMBER>\d+)\)`
+
+i.e.: a number in `()`, with or without a leading `#` (inside the braces).
+
+The `ISSUE_NUMBER` must correspond to an **OPEN** Issue in the repo that the Action is running against.
+
+If the issue has been closed or can't be found then the comment is marked as an error and the Check with fail.
+
+## Example Use as a ForgeJo Action Step
+
+```yaml
+jobs:
+  tests:
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Check TODOs
+        uses: https://git.kemitix.net/kemitix/forgejo-todo-checker@v1
+```
+
+The output will be similar to the following if there are any errors:
+
+```
+Forgejo TODO Checker!
+Repo: kemitix/my-projext
+Prefix: (#|//)\s*(TODO|FIXME)
+Issues: ( |)(\(|\(#)(?P<ISSUE_NUMBER>\d+)(\))
+- Invalid: src/main.rs#38:
+ // TODO: implement this cool feature and get rich!
+- Closed : (19) README.md#12:
+ // TODO: (#19) This is the comment
+
+Error: Invalid or closed TODO/FIXMEs found
+```
+
+The first error is because there is no issue number associated with the TODO comment.
+
+The second error is because the issue has already been closed. 
+
+## License
+
+`forgejo-todo-checker` is released under the MIT License.