Add docs for AG001 (#5)

* Add docs

* fix tests

---------

Co-authored-by: Joel Dickson <[email protected]>

doc/AG001.md

@@ -0,0 +1,42 @@
+# AG001: Ignored Return Value Rule
+
+This rule detects instances where return values from function calls 
+are ignored, which can lead to potential bugs.
+
+## Description
+
+Ignoring return values often indicates that a function is being called 
+solely for its side effects, which can be a code smell. This practice 
+can result in:
+
+1. Wasted computation
+2. Missed error handling
+3. Unexpected behavior
+
+## Noncompliant Code Examples
+
+```kotlin
+toUppercase("hello")  // Noncompliant: Return value is ignored
+getNumbers().filter { it > 2 }  // Noncompliant: Return value is ignored
+userManager.login("user", "password")  // Noncompliant: Return value is ignored
+```
+
+## Compliant Code Examples
+
+```kotlin
+val uppercased = toUppercase("hello")
+val filteredNumbers = getNumbers().filter { it > 2 }
+val loginSuccessful = userManager.login("user", "password")
+```
+
+## Exceptions
+
+The rule does not flag:
+- Functions returning `Unit` or `Nothing`
+- Cases where the return value is explicitly ignored using an underscore:
+
+```kotlin
+_ = toUppercase("hello")  // Compliant: Explicitly ignored
+```
+We recognise that sometimes you do want to ignore the return value, 
+by making it explicit then we know its not a bug and it's intentional.

src/main/kotlin/io/agodadev/kraftdetekt/IgnoredReturnValueRule.kt

@@ -9,15 +9,18 @@ import org.jetbrains.kotlin.resolve.calls.util.getResolvedCall
 import org.jetbrains.kotlin.types.typeUtil.isNothing
 import org.jetbrains.kotlin.types.typeUtil.isUnit
 
+const val IGNORED_RETURN_VALUE: String = "AG001: The return value of this function call is ignored. see https://github.com/agoda-com/agoda-kraft/blob/main/doc/AG001.md"
+
 @RequiresTypeResolution
 class IgnoredReturnValueRule(config: Config) : Rule(config) {
     override val issue = Issue(
         javaClass.simpleName,
         Severity.Warning,
-        "This rule reports when a function call's return value is ignored.",
+        "AG001: This rule reports when a function call's return value is ignored. see https://github.com/agoda-com/agoda-kraft/blob/main/doc/AG001.md",
         Debt.FIVE_MINS
     )
 
+
     override fun visitCallExpression(expression: KtCallExpression) {
         super.visitCallExpression(expression)
 
@@ -47,15 +50,15 @@ class IgnoredReturnValueRule(config: Config) : Rule(config) {
                         report(CodeSmell(
                             issue,
                             Entity.from(expression),
-                            "The return value of this function call is ignored."
+                            IGNORED_RETURN_VALUE
                         ))
                     }
                 }
                 else -> {
                     report(CodeSmell(
                         issue,
                         Entity.from(expression),
-                        "The return value of this function call is ignored."
+                        IGNORED_RETURN_VALUE
                     ))
                 }
             }

src/test/kotlin/io/agodadev/kraftdetekt/IgnoredReturnValueRuleTest.kt

@@ -46,7 +46,7 @@ class IgnoredReturnValueRuleTest(private val env: KotlinCoreEnvironment) {
             "Test.kt\$returnsInt()"
         )
         findings.forEach { finding ->
-            assertThat(finding.message).isEqualTo("The return value of this function call is ignored.")
+            assertThat(finding.message).isEqualTo(IGNORED_RETURN_VALUE)
         }
     }