Chore: improve documentation and error messages

scripts/generateDocs.ts

@@ -31,6 +31,7 @@ import MarkdownUtils from "../src/Utils/MarkdownUtils"
 import { parse as parse_html } from "node-html-parser"
 import { AvailableRasterLayers } from "../src/Models/RasterLayers"
 import { ImmutableStore } from "../src/Logic/UIEventSource"
+import * as unitUsage from "../Docs/Schemas/UnitConfigJson.schema.json"
 
 /**
  * Converts a markdown-file into a .json file, which a walkthrough/slideshow element can use
@@ -268,7 +269,12 @@ export class GenerateDocs extends Script {
 
     private generateBuiltinUnits() {
         const layer = new LayerConfig(<LayerConfigJson>unit, "units", true)
-        const els: string[] = ["## " + layer.id]
+        const els: string[] = [
+            "# Units",
+            "## How to use",
+            unitUsage.description,
+            "Units ",
+            "## " + layer.id]
 
         for (const unit of layer.units) {
             els.push("### " + unit.quantity)
@@ -295,8 +301,8 @@ export class GenerateDocs extends Script {
             }
         }
 
-        this.WriteMarkdownFile("./Docs/builtin_units.md", ["# Units", ...els].join("\n\n"), [
+        this.WriteMarkdownFile("./Docs/builtin_units.md", els.join("\n\n"), [
-            `assets/layers/unit/unit.json`,
+            `assets/layers/unit/unit.json`, `src/Models/ThemeConfig/Json/UnitConfigJson.ts`
         ])
     }
 

scripts/generateTaginfoProjectFiles.ts

@@ -74,7 +74,7 @@ function generateLayerUsage(layer: LayerConfig): TagInfoPrototype[] {
             const usesImageUpload = (tr.render?.txt?.indexOf("image_upload") ?? -2) > 0
 
             if (usesImageCarousel || usesImageUpload) {
-                const descrNoUpload = `Images  are displayed based on the keys image, image:0, image:1,..., panoramax, panoramax:0, panoramx:1, ... ,  wikidata, wikipedia, wikimedia_commons and mapillary`
+                const descrNoUpload = `Images are displayed based on the keys image, image:0, image:1,..., panoramax, panoramax:0, panoramx:1, ... ,  wikidata, wikipedia, wikimedia_commons and mapillary`
                 const descrUpload = `${descrNoUpload} Furthermore, this layer shows images based on the keys panoramax, image, wikidata, wikipedia, wikimedia_commons and mapillary`
 
                 const shownText = (usesImageUpload ? descrUpload : descrNoUpload) + condition

src/Models/ThemeConfig/Conversion/Conversion.ts

@@ -151,7 +151,11 @@ export class Each<X, Y> extends Conversion<X[], Y[]> {
                     values[i]?.["id"] !== undefined ? values[i]?.["id"] : ""
                 )
             }
-            const r = step.convert(values[i], c.enter(i))
+            let id = ""
+            if (values[i]?.["id"]) {
+                id = `(${values[i]?.["id"]})`
+            }
+            const r = step.convert(values[i], c.enter(i + id))
             result.push(r)
         }
         return result

src/Models/ThemeConfig/Json/UnitConfigJson.ts

@@ -1,5 +1,5 @@
 /**
- * In some cases, a value is represented in a certain unit (such as meters for heigt/distance/..., km/h for speed, ...)
+ * In some cases, a value is represented in a certain unit (such as meters for height/distance/..., km/h for speed, ...)
  *
  * Sometimes, multiple denominations are possible (e.g. km/h vs mile/h; megawatt vs kilowatt vs gigawatt for power generators, ...)
  *
@@ -14,9 +14,9 @@
  *
  * # Usage
  *
- * First of all, you define which keys have units applied, for example:
+ * First of all, you define which keys have units applied. This can be done centrally in the layer:
  *
- * ```
+ * ```json
  * units: [
  *  appliesTo: ["maxspeed", "maxspeed:hgv", "maxspeed:bus"]
  *  applicableUnits: [

src/Models/ThemeConfig/TagRenderingConfig.ts

@@ -197,7 +197,7 @@ export default class TagRenderingConfig {
                     json.freeform.key,
                     <any>Validators.availableTypes,
                     (s) => <any>s
-                )}`
+                )}. See https://source.mapcomplete.org/MapComplete/MapComplete/src/branch/develop/Docs/SpecialInputElements.md for more information`
             }
             const type: ValidatorType = <any>json.freeform.type ?? "string"
 

src/UI/InputElement/Validators/OpeningHoursValidator.ts

@@ -7,7 +7,7 @@ export default class OpeningHoursValidator extends Validator {
             "opening_hours",
             [
                 "Has extra elements to easily input when a POI is opened.",
-                "### Helper arguments",
+                "#### Helper arguments",
                 "Only one helper argument named `options` can be provided. It is a JSON-object of type `{ prefix: string, postfix: string }`:",
                 MarkdownUtils.table(
                     ["subarg", "doc"],
@@ -22,7 +22,7 @@ export default class OpeningHoursValidator extends Validator {
                         ],
                     ]
                 ),
-                "### Example usage",
+                "#### Example usage",
                 "To add a conditional (based on time) access restriction:\n\n```\n" +
                     `
 "freeform": {

src/UI/InputElement/Validators/WikidataValidator.ts

@@ -1,17 +1,14 @@
-import Combine from "../../Base/Combine"
 import Wikidata, { WikidataResponse } from "../../../Logic/Web/Wikidata"
 import { Validator } from "../Validator"
 import { Translation } from "../../i18n/Translation"
 import Translations from "../../i18n/Translations"
-import Title from "../../Base/Title"
-import Table from "../../Base/Table"
 import MarkdownUtils from "../../../Utils/MarkdownUtils"
 
 export default class WikidataValidator extends Validator {
     public static readonly _searchCache = new Map<string, Promise<WikidataResponse[]>>()
 
-    public static docs = [
+    private static docs = [
-        "### Helper arguments",
+        "#### Helper arguments",
         MarkdownUtils.table(
             ["name", "doc"],
             [
@@ -25,7 +22,7 @@ export default class WikidataValidator extends Validator {
                 ],
             ]
         ),
-        "#### Suboptions",
+        "##### Suboptions",
         MarkdownUtils.table(
             ["subarg", "doc"],
             [
@@ -50,7 +47,7 @@ export default class WikidataValidator extends Validator {
         ),
     ].join("\n\n")
     private static readonly docsExampleUsage: string =
-        "### Example usage\n\n" +
+        "#### Example usage\n\n" +
         `The following is the 'freeform'-part of a layer config which will trigger a search for the wikidata item corresponding with the name of the selected feature. It will also remove '-street', '-square', ... if found at the end of the name
 
 \`\`\`json
@@ -113,7 +110,7 @@ Another example is to search for species and trees:
         return !str.split(";").some((str) => Wikidata.ExtractKey(str) === undefined)
     }
 
-    getFeedback(s: string, _?: () => string): Translation | undefined {
+    getFeedback(s: string): Translation | undefined {
         const t = Translations.t.validation.wikidata
         if (s === "") {
             return t.empty