Fix building the documentation

* Add `typedoc.json` instead of command-line flags, as the interface changed
* Add plugin to document not exported objects (needed for the gettext module)
* Add some module description for index and gettext

Signed-off-by: Ferdinand Thiessen <rpm@fthiessen.de>

lib/gettext.ts

@@ -1,7 +1,27 @@
+/**
+ * This module provides functionality to translate applications independent from Nextcloud
+ * 
+ * @packageDocumentation
+ * @module @nextcloud/l10n/gettext
+ * @example
+ * ```js
+import { getGettextBuilder } from '@nextcloud/l10n/gettext'
+
+const gt = getGettextBuilder()
+            .detectLocale() // or use setLanguage()
+            .addTranslation(/* ... *\/)
+            .build()
+
+gt.gettext('some string to translate')
+```
+ */
 import GetText from "node-gettext"
 
 import { getLanguage } from "."
 
+/**
+ * @notExported
+ */
 class GettextBuilder {
 
     private locale?: string
@@ -13,6 +33,7 @@ class GettextBuilder {
         return this
     }
 
+    /** Try to detect locale from context with `en` as fallback value */
     detectLocale(): GettextBuilder {
         return this.setLanguage(getLanguage().replace('-', '_'))
     }
@@ -33,6 +54,9 @@ class GettextBuilder {
 
 }
 
+/**
+ * @notExported
+ */
 class GettextWrapper {
 
     private gt: GetText
@@ -50,7 +74,7 @@ class GettextWrapper {
         this.gt.setLocale(locale)
     }
 
-    private subtitudePlaceholders(translated: string, vars: object): string {
+    private subtitudePlaceholders(translated: string, vars: Record<string, string | number>): string {
         return translated.replace(/{([^{}]*)}/g, (a, b) => {
             const r = vars[b]
             if (typeof r === 'string' || typeof r === 'number') {
@@ -61,14 +85,16 @@ class GettextWrapper {
         })
     }
 
-    gettext(original: string, placeholders: object = {}): string {
+    /** Get translated string (singular form), optionally with placeholders */
+    gettext(original: string, placeholders: Record<string, string | number> = {}): string {
         return this.subtitudePlaceholders(
             this.gt.gettext(original),
             placeholders
         )
     }
 
-    ngettext(singular: string, plural: string, count: number, placeholders: object = {}): string {
+    /** Get translated string with plural forms */
+    ngettext(singular: string, plural: string, count: number, placeholders: Record<string, string | number> = {}): string {
         return this.subtitudePlaceholders(
             this.gt.ngettext(singular, plural, count).replace(/%n/g, count.toString()),
             placeholders

lib/index.ts

@@ -1,2 +1,17 @@
+/**
+ * This module provides all functions for the `OC.L10N` namespace
+ * 
+ * @packageDocumentation
+ * @module @nextcloud/l10n
+ * @example
+ * ```js
+import { translate as t, translatePlural as n } from '@nextcloud/l10n'
+
+console.log(t('my-app', 'Hello {name}', { name: 'J. Doe' }));
+const count = 2;
+console.warn(n('my-app', 'Got an error', 'Got multiple errors', 2));
+```
+ */
+
 export * from './translation'
 export * from './date'

lib/translation.ts

@@ -10,6 +10,7 @@ import { generateFilePath } from '@nextcloud/router'
 import DOMPurify from 'dompurify'
 import escapeHTML from 'escape-html'
 
+/** @notExported */
 interface TranslationOptions {
 	/** enable/disable auto escape of placeholders (by default enabled) */
 	escape?: boolean

package.json

@@ -16,7 +16,7 @@
   },
   "scripts": {
     "build": "tsc && tsc --project tsconfig.cjs.json",
-    "build:doc": "typedoc --excludeNotExported --mode file --out dist/doc lib && touch dist/doc/.nojekyll",
+    "build:doc": "typedoc && touch dist/doc/.nojekyll",
     "check-types": "tsc --noEmit",
     "check-es-compat": "npm run build && check-es-compat dist/*.js",
     "dev": "tsc --watch",
@@ -43,6 +43,7 @@
     "@nextcloud/browserslist-config": "^2.3.0",
     "@nextcloud/typings": "^1.0.0",
     "@types/node-gettext": "^3.0",
+    "@zamiell/typedoc-plugin-not-exported": "^0.2.0",
     "check-es-compat": "^2.2.0",
     "gettext-parser": "^6.0.0",
     "jest": "^29.3.1",

typedoc.json

@@ -0,0 +1,10 @@
+{
+    "$schema": "https://typedoc.org/schema.json",
+    "entryPoints": ["./lib/index.ts", "./lib/gettext.ts"],
+    "out": "dist/doc",
+    "excludePrivate": true,
+    "navigationLinks": {
+        "GitHub": "https://github.com/nextcloud/nextcloud-l10n/",
+        "Nextcloud": "https://docs.nextcloud.com/server/stable/developer_manual/basics/front-end/l10n.html"
+    }
+}