From 1c0d19697fb942a5eb7113410e7c1ef3b56d5377 Mon Sep 17 00:00:00 2001
From: Shakar Bakr <5h4k4r.b4kr@gmail.com>
Date: Sun, 15 Jun 2025 14:22:08 +0300
Subject: [PATCH] Add detailed TODO references section to README.md, including
 examples for labels, comments on existing issues, custom references, and
 assignees to enhance documentation clarity and usability.

Signed-off-by: Shakar Bakr <5h4k4r.b4kr@gmail.com>
---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/README.md b/README.md
index 1f344c2..11d80cc 100644
--- a/README.md
+++ b/README.md
@@ -198,6 +198,56 @@ def hello_world():
 
 Only a single milestone can be specified. If the milestone does not exist, it will be created.
 
+## TODO References
+
+TODOs can include references in parentheses to control their behavior:
+
+### Labels
+
+Use `!` to add a label to the issue:
+
+```python
+def calculate_tax():
+    # TODO(!urgent): This is wrong
+    #  This will add an 'urgent' label.
+    assert 1 + 1 == 3
+```
+
+### Comment on Existing Issue
+
+Use `#` followed by an issue number to add a comment to an existing issue instead of creating a new one:
+
+```python
+def parse_date():
+    # TODO(#99): We need error handling here
+    #  This will add the comment to the existing issue 99.
+    greeting_time = datetime.fromisoformat(date_string)
+```
+
+### Custom Reference
+
+Use any other text to prepend a reference to the issue title:
+
+```python
+def get_greeting():
+    # TODO(language): Localise this string
+    #  This will prepend the reference to the issue title
+    dialogue = "TODO or not TODO, that is the question."
+```
+
+### Assignees
+
+Use `@` to assign the issue to a specific user:
+
+```python
+def optimize_performance():
+    # TODO(@username): This needs optimization
+    #  This will assign the issue to 'username'
+    slow_function()
+```
+
+Multiple references can be combined: `# TODO(@alice !priority #123): Fix this`
+
 ## Supported Languages
 
 - ABAP