Resolved #13274 - Added examples for all countables

core/src/com/unciv/models/ruleset/unique/Countables.kt

@@ -5,6 +5,7 @@ import com.unciv.models.ruleset.unique.expressions.Expressions
 import com.unciv.models.ruleset.unique.expressions.Operator
 import com.unciv.models.stats.Stat
 import com.unciv.models.translations.equalsPlaceholderText
+import com.unciv.models.translations.fillPlaceholders
 import com.unciv.models.translations.getPlaceholderParameters
 import com.unciv.models.translations.getPlaceholderText
 import org.jetbrains.annotations.VisibleForTesting
@@ -37,6 +38,7 @@ enum class Countables(
         override val documentationHeader = "Integer constant - any positive or negative integer number"
         override fun matches(parameterText: String) = parameterText.toIntOrNull() != null
         override fun eval(parameterText: String, stateForConditionals: StateForConditionals) = parameterText.toIntOrNull()
+        override val example: String = "123"
     },
 
     Turns("turns", shortDocumentation = "Number of turns played") {
@@ -69,6 +71,8 @@ enum class Countables(
                 return stateForConditionals.civInfo?.getHappiness()
             return stateForConditionals.getStatAmount(relevantStat)
         }
+
+        override val example = "Science"
         override fun getKnownValuesForAutocomplete(ruleset: Ruleset) = Stat.names()
         private fun Iterable<String>.niceJoin() = joinToString("`, `", "`", "`").run {
             val index = lastIndexOf("`, `")
@@ -149,6 +153,8 @@ enum class Countables(
         override fun matches(parameterText: String, ruleset: Ruleset) = parameterText in ruleset.tileResources
         override fun eval(parameterText: String, stateForConditionals: StateForConditionals) =
             stateForConditionals.getResourceAmount(parameterText)
+
+        override val example = "Iron"
         override fun getKnownValuesForAutocomplete(ruleset: Ruleset) = ruleset.tileResources.keys
     },
 
@@ -176,6 +182,7 @@ enum class Countables(
             engine.getErrorSeverity(parameterText, ruleset)
 
         override fun getKnownValuesForAutocomplete(ruleset: Ruleset) = emptySet<String>()
+        override val example: String = "[Iron] + 2"
 
         override val documentationHeader = "Evaluate expressions!"
         override val documentationStrings = listOf(
@@ -209,6 +216,14 @@ enum class Countables(
 
     open val documentationHeader get() =
         "`$text`" + (if (shortDocumentation.isEmpty()) "" else " - $shortDocumentation")
+    
+    open val example: String
+        get() {
+            if (noPlaceholders) return text
+            val placeholderParams = text.getPlaceholderParameters()
+                .map { UniqueParameterType.safeValueOf(it).docExample }
+            return text.fillPlaceholders(*placeholderParams.toTypedArray())
+        }
 
     /** Leave this only for Countables without any parameters - they can rely on [matches] having validated enough */
     open fun getErrorSeverity(parameterText: String, ruleset: Ruleset): UniqueType.UniqueParameterErrorSeverity? = null

desktop/src/com/unciv/app/desktop/UniqueDocsWriter.kt

@@ -155,6 +155,7 @@ class UniqueDocsWriter {
         for (countable in Countables.entries) {
             if (countable.getDeprecationAnnotation() != null) continue
             newContent.appendLine("-   ${countable.documentationHeader}")
+            newContent.appendLine("    - Example: `Only available <when number of [${countable.example}] is more than [0]>`") // Sublist
             for (extraLine in countable.documentationStrings) {
                 newContent.append("    - ") // Sublist
                 newContent.appendLine(extraLine)

docs/Modders/Unique-parameters.md

@@ -341,25 +341,39 @@ Allowed values:
 
 [//]: # (Countables automatically generated BEGIN)
 -   Integer constant - any positive or negative integer number
+    - Example: `Only available <when number of [123] is more than [0]>`
 -   `turns` - Number of turns played
+    - Example: `Only available <when number of [turns] is more than [0]>`
     - Always starts at zero irrespective of game speed or start era
 -   `year` - The current year
+    - Example: `Only available <when number of [year] is more than [0]>`
     - Depends on game speed or start era, negative for years BC
 -   `Cities` - The number of cities the relevant Civilization owns
+    - Example: `Only available <when number of [Cities] is more than [0]>`
 -   `Units` - The number of units the relevant Civilization owns
+    - Example: `Only available <when number of [Units] is more than [0]>`
 -   Stat name (`Production`, `Food`, `Gold`, `Science`, `Culture`, `Happiness` or `Faith`)
+    - Example: `Only available <when number of [Science] is more than [0]>`
     - Gets the stat *reserve*, not the amount per turn (can be city stats or civilization stats, depending on where the unique is used)
 -   `Completed Policy branches`
+    - Example: `Only available <when number of [Completed Policy branches] is more than [0]>`
 -   `[cityFilter] Cities`
+    - Example: `Only available <when number of [[in all cities] Cities] is more than [0]>`
 -   `[mapUnitFilter] Units`
+    - Example: `Only available <when number of [[Wounded] Units] is more than [0]>`
 -   `[buildingFilter] Buildings`
+    - Example: `Only available <when number of [[Culture] Buildings] is more than [0]>`
 -   `Remaining [civFilter] Civilizations`
+    - Example: `Only available <when number of [Remaining [City-States] Civilizations] is more than [0]>`
 -   `Owned [tileFilter] Tiles`
+    - Example: `Only available <when number of [Owned [Farm] Tiles] is more than [0]>`
 -   Resource name - From [TileResources.json](3-Map-related-JSON-files.md#tileresourcesjson)
+    - Example: `Only available <when number of [Iron] is more than [0]>`
     - Can be city stats or civilization stats, depending on where the unique is used
     - For example: If a unique is placed on a building, then the retrieved resources will be of the city. If placed on a policy, they will be of the civilization.
     - This can make a difference for e.g. local resources, which are counted per city.
 -   Evaluate expressions!
+    - Example: `Only available <when number of [[Iron] + 2] is more than [0]>`
     - Expressions support arbitrary math operations, and can include other countables, when surrounded by square brackets.
     - For example, since `Cities` is a countable, and `[Melee] units` is a countable, you can have something like: `([[Melee] units] + 1) / [Cities]` (the whitespace is optional but helps readability)
     - Since on translation, the brackets are removed, the expression will be displayed as `(Melee units + 1) / Cities`