Implement excludePrivateClassFields

resolves #3017

Author: Gerrit0

CHANGELOG.md

@@ -9,6 +9,7 @@ title: Changelog
 - Introduced the `preservedTypeAnnotationTags` option to specify tags whose type annotations should
   be copied to the output documentation, #3020.
   API: Introduced `typeAnnotation` on `CommentTag`
+- Added `excludePrivateClassFields` option to hide `#private` members while allowing `private` members, #3017.
 
 ## Bug Fixes
 

site/options/input.md

@@ -215,7 +215,16 @@ Removes symbols annotated with the `@internal` doc tag. Defaults to true if the
 typedoc --excludePrivate
 ```
 
-Removes private class members from the generated documentation. Defaults to true.
+Removes members marked with `private` and `#private` class fields from the generated documentation. Defaults to true.
+To include `#private` class fields both this option and [excludePrivateClassFields](#excludeprivateclassfields) must be set to `false`.
+
+## excludePrivateClassFields
+
+```bash
+typedoc --excludePrivateClassFields
+```
+
+Removes `#private` class fields from the generated documentation. Defaults to true.
 
 ## excludeProtected
 

site/options/package-options.md

@@ -41,6 +41,7 @@ at the root level. The following tables indicate where an option should be set.
 | [`excludeNotDocumentedKinds`](input.md#excludenotdocumentedkinds)       | Package  |                                                                                                           |
 | [`excludeInternal`](input.md#excludeinternal)                           | Package  |                                                                                                           |
 | [`excludePrivate`](input.md#excludeprivate)                             | Package  |                                                                                                           |
+| [`excludePrivateClassFields`](input.md#excludeprivateclassfields)       | Package  |                                                                                                           |
 | [`excludeProtected`](input.md#excludeprotected)                         | Package  |                                                                                                           |
 | [`excludeReferences`](input.md#excludereferences)                       | Package  |                                                                                                           |
 | [`excludeCategories`](input.md#excludecategories)                       | Package  |                                                                                                           |

src/lib/converter/plugins/CommentPlugin.ts

@@ -134,6 +134,9 @@ export class CommentPlugin extends ConverterComponent {
     @Option("excludePrivate")
     accessor excludePrivate!: boolean;
 
+    @Option("excludePrivateClassFields")
+    accessor excludePrivateClassFields!: boolean;
+
     @Option("excludeProtected")
     accessor excludeProtected!: boolean;
 
@@ -567,6 +570,19 @@ export class CommentPlugin extends ConverterComponent {
             return true;
         }
 
+        // #3017 this isn't quite right as it may incorrectly detect
+        // private members named with a hash which aren't actually private
+        // class fields (e.g. class Foo { "#hash" = 1 })
+        // We can't fix this without storing more information about the name,
+        // which I'm going to put off until #3015 is done.
+        if (
+            reflection.flags.hasFlag(ReflectionFlag.Private) &&
+            reflection.name.startsWith("#") &&
+            this.excludePrivateClassFields
+        ) {
+            return true;
+        }
+
         if (
             reflection.flags.hasFlag(ReflectionFlag.Protected) &&
             this.excludeProtected

src/lib/internationalization/locales/de.cts

@@ -284,7 +284,6 @@ export = localeUtils.buildIncompleteTranslation({
     help_excludeNotDocumentedKinds: "Arten von Reflections, die von excludeNotDocumented entfernt werden können",
     help_excludeInternal: "Verhindert, dass Symbole in der Dokumentation erscheinen, die mit @internal markiert sind",
     help_excludeCategories: "Schließt Symbole aus dieser Kategorie von der Dokumentation aus",
-    help_excludePrivate: "Ignoriert private Variablen und Methoden, Standardwert ist true.",
     help_excludeProtected: "Ignoriert geschützte Variablen und Methoden",
     help_excludeReferences: "Wird ein Symbol mehrfach exportiert, ignoriere alle außer dem ersten Export",
     help_externalSymbolLinkMappings:

src/lib/internationalization/locales/en.cts

@@ -276,7 +276,8 @@ export = {
     help_excludeNotDocumentedKinds: "Specify the type of reflections that can be removed by excludeNotDocumented",
     help_excludeInternal: "Prevent symbols that are marked with @internal from being documented",
     help_excludeCategories: "Exclude symbols within this category from the documentation",
-    help_excludePrivate: "Ignore private variables and methods, defaults to true.",
+    help_excludePrivate: "Ignore members marked with the private keyword and #private class fields, defaults to true.",
+    help_excludePrivateClassFields: "Ignore #private class fields, defaults to true.",
     help_excludeProtected: "Ignore protected variables and methods",
     help_excludeReferences: "If a symbol is exported multiple times, ignore all but the first export",
     help_externalSymbolLinkMappings: "Define custom links for symbols not included in the documentation",

src/lib/internationalization/locales/ja.cts

@@ -194,7 +194,6 @@ export = localeUtils.buildIncompleteTranslation({
     help_excludeNotDocumentedKinds: "excludeNotDocumented によって削除できる反射の種類を指定します",
     help_excludeInternal: "@internal でマークされたシンボルがドキュメント化されないようにする",
     help_excludeCategories: "このカテゴリ内のシンボルをドキュメントから除外する",
-    help_excludePrivate: "プライベート変数とメソッドを無視します。デフォルトは true です。",
     help_excludeProtected: "保護された変数とメソッドを無視する",
     help_excludeReferences: "シンボルが複数回エクスポートされた場合、最初のエクスポート以外はすべて無視されます。",
     help_externalSymbolLinkMappings: "ドキュメントに含まれていないシンボルのカスタムリンクを定義する",

src/lib/internationalization/locales/ko.cts

@@ -62,7 +62,6 @@ export = localeUtils.buildIncompleteTranslation({
     help_excludeNotDocumentedKinds: "excludeNotDocumented로 제거될 리플렉션 유형을 지정합니다",
     help_excludeInternal: "@internal로 표시된 심볼이 문서화되지 않도록 방지합니다",
     help_excludeCategories: "문서에서 제외할 카테고리 내의 심볼을 제외합니다",
-    help_excludePrivate: "비공개 변수와 메서드를 무시합니다. 기본값은 true입니다.",
     help_excludeProtected: "보호된 변수와 메서드를 무시합니다",
     help_excludeReferences: "심볼이 여러 번 내보내진 경우 첫 번째 내보내기를 제외하고 모두 무시합니다",
     help_externalSymbolLinkMappings: "문서에 포함되지 않은 심볼에 대한 사용자 정의 링크를 정의합니다",

src/lib/internationalization/locales/zh.cts

@@ -233,7 +233,6 @@ export = localeUtils.buildIncompleteTranslation({
     help_excludeNotDocumentedKinds: "指定可以通过 excludeNotDocumented 删除的反射类型",
     help_excludeInternal: "防止标有 @internal 的符号被记录",
     help_excludeCategories: "从文档中排除此类别中的符号",
-    help_excludePrivate: "忽略私有变量和方法，默认为 true。",
     help_excludeProtected: "忽略受保护的变量和方法",
     help_excludeReferences: "如果一个符号被导出多次，则忽略除第一次导出之外的所有导出",
     help_externalSymbolLinkMappings: "为文档中未包含的符号定义自定义链接",

src/lib/utils/options/declaration.ts

@@ -207,6 +207,7 @@ export interface TypeDocOptionMap {
     excludeNotDocumented: boolean;
     excludeNotDocumentedKinds: ReflectionKind.KindString[];
     excludeInternal: boolean;
+    excludePrivateClassFields: boolean;
     excludePrivate: boolean;
     excludeProtected: boolean;
     excludeReferences: boolean;