From 6de1e38ce094b2e136c8179646a7d07f86f9718b Mon Sep 17 00:00:00 2001
From: Gerrit Birkeland <gerrit@gerritbirkeland.com>
Date: Sat, 30 Jul 2022 08:19:10 -0600
Subject: [PATCH] Add question mark when rendering optional property name

Resolves #2023
---
 .config/typedoc.json                              |  1 +
 CHANGELOG.md                                      |  2 ++
 scripts/generate_options_schema.js                |  4 ++++
 src/lib/output/themes/default/partials/index.tsx  |  4 ++--
 .../output/themes/default/partials/navigation.tsx |  6 +++---
 src/lib/output/themes/lib.tsx                     | 15 +++++++++++++++
 6 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/.config/typedoc.json b/.config/typedoc.json
index ae6df8d04..f3c932a86 100644
--- a/.config/typedoc.json
+++ b/.config/typedoc.json
@@ -10,6 +10,7 @@
         "EventHooksMomento",
         "MarkedPlugin"
     ],
+    "sort": ["kind", "instance-first", "required-first", "alphabetical"],
     "entryPoints": ["../src"],
     "entryPointStrategy": "resolve",
     "excludeExternals": true,
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5ba178ca5..a0200942f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@
 
 -   Added support for detecting comments directly before parameters as the parameter comment, #2019.
 -   Added support for using the comment directly before a constructor parameter that declares a property as the property comment, #2019.
+-   Improved schema generation to give better autocomplete for the `sort` option.
+-   Optional properties are now visually distinguished in the index/sidebar by rendering `prop` as `prop?`, #2023.
 
 ### Bug Fixes
 
diff --git a/scripts/generate_options_schema.js b/scripts/generate_options_schema.js
index 11c66b77f..b3c9f4e51 100644
--- a/scripts/generate_options_schema.js
+++ b/scripts/generate_options_schema.js
@@ -153,6 +153,10 @@ schema.properties.extends = {
     items: { type: "string" },
 };
 
+delete schema.properties.sort.items.type;
+schema.properties.sort.items.enum =
+    require("../dist/lib/utils/sort").SORT_STRATEGIES;
+
 const output = JSON.stringify(schema, null, "\t");
 
 if (process.argv.length > 2) {
diff --git a/src/lib/output/themes/default/partials/index.tsx b/src/lib/output/themes/default/partials/index.tsx
index ff0e46945..40b3d7f4d 100644
--- a/src/lib/output/themes/default/partials/index.tsx
+++ b/src/lib/output/themes/default/partials/index.tsx
@@ -1,4 +1,4 @@
-import { classNames, displayPartsToMarkdown, wbr } from "../../lib";
+import { classNames, displayPartsToMarkdown, renderName } from "../../lib";
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
 import { JSX, Raw } from "../../../../utils";
 import { ContainerReflection, DeclarationReflection, ReflectionCategory, ReflectionKind } from "../../../../models";
@@ -18,7 +18,7 @@ function renderCategory({ urlTo, icons }: DefaultThemeRenderContext, item: Refle
                             )}
                         >
                             {icons[item.kind]()}
-                            <span>{item.name ? wbr(item.name) : <em>{wbr(item.kindString!)}</em>}</span>
+                            <span>{renderName(item)}</span>
                         </a>
                         {"\n"}
                     </>
diff --git a/src/lib/output/themes/default/partials/navigation.tsx b/src/lib/output/themes/default/partials/navigation.tsx
index 5a0487538..e2cd16e6e 100644
--- a/src/lib/output/themes/default/partials/navigation.tsx
+++ b/src/lib/output/themes/default/partials/navigation.tsx
@@ -1,7 +1,7 @@
 import { ContainerReflection, DeclarationReflection, Reflection, ReflectionKind } from "../../../../models";
 import { JSX, partition } from "../../../../utils";
 import type { PageEvent } from "../../../events";
-import { camelToTitleCase, classNames, wbr } from "../../lib";
+import { camelToTitleCase, classNames, renderName, wbr } from "../../lib";
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
 
 export function navigation(context: DefaultThemeRenderContext, props: PageEvent<Reflection>) {
@@ -155,7 +155,7 @@ export function secondaryNavigation(context: DefaultThemeRenderContext, props: P
                 >
                     <a href={context.urlTo(child)} class="tsd-index-link">
                         {context.icons[child.kind]()}
-                        {wbr(child.name)}
+                        {renderName(child)}
                     </a>
                 </li>
             );
@@ -183,7 +183,7 @@ export function secondaryNavigation(context: DefaultThemeRenderContext, props: P
                 >
                     <a href={context.urlTo(effectivePageParent)} class="tsd-index-link">
                         {context.icons[effectivePageParent.kind]()}
-                        <span>{wbr(effectivePageParent.name)}</span>
+                        <span>{renderName(effectivePageParent)}</span>
                     </a>
                     {!!pageNavigation.length && <ul>{pageNavigation}</ul>}
                 </li>
diff --git a/src/lib/output/themes/lib.tsx b/src/lib/output/themes/lib.tsx
index d2e0f7972..834c7faa2 100644
--- a/src/lib/output/themes/lib.tsx
+++ b/src/lib/output/themes/lib.tsx
@@ -157,3 +157,18 @@ export function displayPartsToMarkdown(parts: CommentDisplayPart[], urlTo: Defau
 
     return result.join("");
 }
+
+/**
+ * Renders the reflection name with an additional `?` if optional.
+ */
+export function renderName(refl: Reflection) {
+    if (!refl.name) {
+        return <em>{wbr(refl.kindString!)}</em>;
+    }
+
+    if (refl.flags.isOptional) {
+        return <>{wbr(refl.name)}?</>;
+    }
+
+    return wbr(refl.name);
+}