Add new option for replacing text in comment tags

krisztianb · Apr 7, 2022 · 44d4fb7 · 44d4fb7
1 parent 2a8ead5
commit 44d4fb7
Show file tree

Hide file tree

Showing 4 changed files with 85 additions and 48 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,8 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [1.0.0] - 2020-09-12
+## [1.0.0] - 2022-04-07
 First release
 
-[unreleased]: https://github.com/krisztianb/typedoc-plugin-replace-in-comments/compare/v1.0.0...HEAD
-[1.0.0]: https://github.com/krisztianb/typedoc-plugin-replace-in-comments/releases/tag/v1.0.0
+[unreleased]: https://github.com/krisztianb/typedoc-plugin-replace-text/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/krisztianb/typedoc-plugin-replace-text/releases/tag/v1.0.0
diff --git a/README.md b/README.md
@@ -17,6 +17,7 @@ This can be useful for:
 -   Creating links from author names (eg: link "Your Name" to your GitHub or corporate profile page)
 -   Replacing internal URLs with external ones
 -   Replacing custom placeholders with anything you like (eg: images)
+-   Remove or replace text in your README.md file that is included by TypeDoc
 -   Remove URLs or other text
 -   etc.
 
@@ -28,8 +29,7 @@ This module can be installed using [npm](https://www.npmjs.com/package/typedoc-p
 $ npm install typedoc-plugin-replace-text --save-dev
 ```
 
-TypeDoc automatically detects plugins installed via npm. After installation TypeDoc can be used normally and you can
-configure this plugin as described below.
+TypeDoc automatically detects plugins installed via npm. After installation TypeDoc can be used normally and you can configure this plugin as described below.
 
 ### Requirements
 
@@ -41,8 +41,9 @@ Extend your [TypeDoc config file](https://typedoc.org/guides/options/) with a ne
 
 ```json
 "replaceText": {
-    "inCodeComments": true,
-    "inReadme": true,
+    "inCodeCommentText": true,
+    "inCodeCommentTags": true,
+    "inIncludedFiles": true,
     "replacements": [
         {
             "pattern": "(GH-(\\d+))",
@@ -59,11 +60,12 @@ Extend your [TypeDoc config file](https://typedoc.org/guides/options/) with a ne
 
 Explanation:
 
-| Property           | Description                                                                   |
-| ------------------ | ----------------------------------------------------------------------------- |
-| **inCodeComments** | Specifies if the plugin should replace in code comments. (optional - defaults to `true`) |
-| **inReadme**       | Specifies if the plugin should replace in your README file. (optional - defaults to `true`) |
-| **replacements**   | The search patterns and texts they should be replaced with. (`pattern` is the search Regex, `flags` are the optional Regex flags that default to `g` and `replace` is the inserted text) |
+| Property              | Description                                                                   |
+| --------------------- | ----------------------------------------------------------------------------- |
+| **inCodeCommentText** | Specifies if the plugin should replace in the text of comments (not including the text of tags like the description of parameters for a method) in your code. (optional - defaults to `true`) |
+| **inCodeCommentTags** | Specifies if the plugin should replace in the text of tags (like the description of parameters for a method) in your code comments. (optional - defaults to `true`) |
+| **inIncludedFiles**   | Specifies if the plugin should replace in your README file. (optional - defaults to `true`) |
+| **replacements**      | The search patterns and texts they should be replaced with. (`pattern` is the search Regex, `flags` are the optional Regex flags that default to `g` and `replace` is the inserted text) |
 
 ## Bugs
 

diff --git a/src/plugin.ts b/src/plugin.ts
@@ -2,16 +2,16 @@ import { Application, Context, Converter } from "typedoc";
 import { PluginOptions } from "./plugin_options";
 
 /**
- * The "replace in comments" plugin.
+ * The "Replace Text" plugin.
  *
  * # What does it do?
  *
- * This plugin replaces text in comments with other text.
+ * This plugin replaces text in the documentation with other text.
  *
  * # How does it do it?
  *
  * The plugin scans through all comments of all reflections and uses the replacment patterns specified
- * by the user to replace text in these comments.
+ * by the user to replace texts.
  */
 export class Plugin {
     /** The options of this plugin. */
@@ -49,28 +49,45 @@ export class Plugin {
      * @param context Describes the current state the converter is in.
      */
     public onConverterResolveBegin(context: Readonly<Context>): void {
-        if (this.options.replacements.length > 0) {
-            const project = context.project;
+        if (!this.hasSomethingTodo) {
+            return;
+        }
 
-            if (this.options.replaceInReadme && project.readme) {
-                project.readme = this.applyReplacements(project.readme);
-            }
+        const project = context.project;
 
-            if (this.options.replaceInCodeComments) {
-                // go through all the reflections' comments
-                for (const key in project.reflections) {
-                    const reflection = project.reflections[key];
+        if (this.options.replaceInIncludedFiles && project.readme) {
+            project.readme = this.applyReplacements(project.readme);
+        }
 
-                    if (reflection.comment) {
-                        reflection.comment.shortText = this.applyReplacements(reflection.comment.shortText);
-                        reflection.comment.text = this.applyReplacements(reflection.comment.text);
-                        reflection.comment.tags.forEach((t) => (t.text = this.applyReplacements(t.text)));
-                    }
+        // go through all the reflections' comments
+        for (const key in project.reflections) {
+            const reflection = project.reflections[key];
+
+            if (reflection.comment) {
+                if (this.options.replaceInCodeCommentText) {
+                    reflection.comment.shortText = this.applyReplacements(reflection.comment.shortText);
+                    reflection.comment.text = this.applyReplacements(reflection.comment.text);
+                }
+                if (this.options.replaceInCodeCommentTags) {
+                    reflection.comment.tags.forEach((t) => (t.text = this.applyReplacements(t.text)));
                 }
             }
         }
     }
 
+    /**
+     * Checks if the plugin is configured in a way that it has something to do.
+     * @returns True, if the plugin has something to do, otherwise false.
+     */
+    private get hasSomethingTodo(): boolean {
+        const shouldReplaceSomething =
+            this.options.replaceInCodeCommentText ||
+            this.options.replaceInCodeCommentTags ||
+            this.options.replaceInIncludedFiles;
+
+        return shouldReplaceSomething && this.options.replacements.length > 0;
+    }
+
     /**
      * Applies the replacements to the given text.
      * @param text The text on which to apply the replacements.

diff --git a/src/plugin_options.ts b/src/plugin_options.ts
@@ -14,11 +14,14 @@ declare module "typedoc" {
  * A type for the options of the plugin.
  */
 type PluginConfig = {
-    /** Should the plugin replace in code comments? */
-    inCodeComments?: boolean;
+    /** Should the plugin replace in the text of code comments? */
+    inCodeCommentText?: boolean;
+
+    /** Should the plugin replace in the text of code comment tags? */
+    inCodeCommentTags?: boolean;
 
     /** Should the plugin replace in the content of the README.md file? */
-    inReadme?: boolean;
+    inIncludedFiles?: boolean;
 
     /** The objects describing what and with what it should be replaced. */
     replacements?: ReplaceInfoFromConfig[];
@@ -53,11 +56,14 @@ type ReplaceInfoWithRegex = {
  * Class storing the options of the plugin.
  */
 export class PluginOptions {
-    /** Should the plugin replace in code comments? */
-    private _replaceInCodeComments = true;
+    /** Should the plugin replace in the text of code comments? */
+    private _replaceInCodeCommentText = true;
+
+    /** Should the plugin replace in the text of code comment tags? */
+    private _replaceInCodeCommentTags = true;
 
     /** Should the plugin replace in the content of the README.md file? */
-    private _replaceInReadme = true;
+    private _replaceInIncludedFiles = true;
 
     /** The replace information. */
     private _replacements: ReplaceInfoWithRegex[] = [];
@@ -71,8 +77,8 @@ export class PluginOptions {
         typedoc.options.addDeclaration({
             type: ParameterType.Mixed,
             name: "replaceText",
-            help: "The array with the objects defining the replacement patterns.",
-            defaultValue: [],
+            help: "The configuration object of the replace-text plugin.",
+            defaultValue: {},
         });
     }
 
@@ -81,16 +87,20 @@ export class PluginOptions {
      * @param typedoc The TypeDoc application.
      */
     public readValuesFromApplication(typedoc: Readonly<Application>): void {
-        // Yes this type assertion sucks, but there's something wrong with the Type Definitions of TypeDoc
+        // Yes, this type assertion sucks, but there's something wrong with the Type Definitions of TypeDoc
         const config = typedoc.options.getValue("replaceText") as unknown as PluginConfig | undefined;
 
         if (config) {
-            if (config.inCodeComments !== undefined) {
-                this._replaceInCodeComments = config.inCodeComments;
+            if (config.inCodeCommentText !== undefined) {
+                this._replaceInCodeCommentText = config.inCodeCommentText;
+            }
+
+            if (config.inCodeCommentTags !== undefined) {
+                this._replaceInCodeCommentTags = config.inCodeCommentTags;
             }
 
-            if (config.inReadme !== undefined) {
-                this._replaceInReadme = config.inReadme;
+            if (config.inIncludedFiles !== undefined) {
+                this._replaceInIncludedFiles = config.inIncludedFiles;
             }
 
             if (Array.isArray(config.replacements)) {
@@ -103,19 +113,27 @@ export class PluginOptions {
     }
 
     /**
-     * Returns if the plugin should apply the replacements to code comments.
-     * @returns True if the plugin should apply the replacements to code comments, otherwise false.
+     * Returns if the plugin should apply the replacements to the text of code comments.
+     * @returns True if the plugin should apply the replacements to the text of code comments, otherwise false.
+     */
+    public get replaceInCodeCommentText(): boolean {
+        return this._replaceInCodeCommentText;
+    }
+
+    /**
+     * Returns if the plugin should apply the replacements to the text of code comment tags.
+     * @returns True if the plugin should apply the replacements to the text of code comment tags, otherwise false.
      */
-    public get replaceInCodeComments(): boolean {
-        return this._replaceInCodeComments;
+    public get replaceInCodeCommentTags(): boolean {
+        return this._replaceInCodeCommentTags;
     }
 
     /**
      * Returns if the plugin should apply the replacements to the README.md content.
      * @returns True if the plugin should apply the replacements to the README.md content, otherwise false.
      */
-    public get replaceInReadme(): boolean {
-        return this._replaceInReadme;
+    public get replaceInIncludedFiles(): boolean {
+        return this._replaceInIncludedFiles;
     }
 
     /**