Merge pull request #546 from nextcloud/fix/documentaton

.github/workflows/documentation.yml

@@ -0,0 +1,32 @@
+name: Deploy documentation
+on:
+ push:
+ branches:
+ - master
+
+permissions:
+ contents: write
+
+jobs:
+ build-and-deploy:
+ concurrency: ci-${{ github.ref }}
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v3
+
+ - name: Set up node
+ uses: actions/setup-node@v3
+ with:
+ node-version-file: 'package.json'
+
+ - name: Install dependencies & build
+ run: |
+ npm ci
+ npm run build:doc
+
+ - name: Deploy
+ uses: JamesIves/github-pages-deploy-action@v4
+ with:
+ folder: dist/doc
+ branch: gh-pages

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"
+ }
+}