Merge branch 'master' into cary-hu/master

Author: Gerrit0

.config/typedoc.json

@@ -11,7 +11,7 @@
         "MarkedPlugin"
     ],
     "entryPoints": ["../src"],
-    "entryPointStrategy": "Resolve",
+    "entryPointStrategy": "resolve",
     "excludeExternals": true,
     "excludeInternal": false,
     "excludePrivate": true,

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Unreleased
 
+### Features
+
+-   Added support for `*.ghe.com` and `*.github.us` GitHub enterprise domains for source links, #2001.
+-   Expose `Converter.parseRawComment` for plugins to parse additional markdown files, #2004.
+-   Added defined in links for classes, enums #180.
+
+### Bug Fixes
+
+-   Fixed missing `sources` property on signature reflections #1996.
+
+### Thanks!
+
+-   @chadhietala
+
 ## v0.23.7 (2022-07-09)
 
 ### Bug Fixes

src/lib/converter/converter.ts

@@ -94,7 +94,8 @@ export class Converter extends ChildableComponent<
 
     /**
      * Triggered when the converter has created a signature reflection.
-     * The listener will be given {@link Context}, {@link SignatureReflection} | {@link ProjectReflection} and a `ts.Node?`
+     * The listener will be given {@link Context}, {@link SignatureReflection} | {@link ProjectReflection} and
+     * `ts.SignatureDeclaration | ts.IndexSignatureDeclaration | ts.JSDocSignature | undefined`
      * @event
      */
     static readonly EVENT_CREATE_SIGNATURE = ConverterEvents.CREATE_SIGNATURE;
@@ -183,6 +184,18 @@ export class Converter extends ChildableComponent<
         return convertType(context, node);
     }
 
+    /**
+     * Parse the given file into a comment. Intended to be used with markdown files.
+     */
+    parseRawComment(file: MinimalSourceFile) {
+        return parseComment(
+            lexCommentString(file.text),
+            this.config,
+            file,
+            this.application.logger
+        );
+    }
+
     /**
      * Compile the files within the given context and convert the compiler symbols to reflections.
      *
@@ -264,11 +277,8 @@ export class Converter extends ChildableComponent<
 
             if (entryPoint.readmeFile) {
                 const readme = readFile(entryPoint.readmeFile);
-                const comment = parseComment(
-                    lexCommentString(readme),
-                    context.converter.config,
-                    new MinimalSourceFile(readme, entryPoint.readmeFile),
-                    context.logger
+                const comment = this.parseRawComment(
+                    new MinimalSourceFile(readme, entryPoint.readmeFile)
                 );
 
                 if (comment.blockTags.length || comment.modifierTags.size) {

src/lib/converter/factories/signature.ts

@@ -98,7 +98,7 @@ export function createSignature(
             break;
     }
 
-    context.trigger(ConverterEvents.CREATE_SIGNATURE, sigRef);
+    context.trigger(ConverterEvents.CREATE_SIGNATURE, sigRef, declaration);
 }
 
 function convertParameters(

src/lib/converter/plugins/PackagePlugin.ts

@@ -7,8 +7,6 @@ import type { Context } from "../context";
 import { BindOption, EntryPointStrategy, readFile } from "../../utils";
 import { getCommonDirectory } from "../../utils/fs";
 import { nicePath } from "../../utils/paths";
-import { lexCommentString } from "../comments/rawLexer";
-import { parseComment } from "../comments/parser";
 import { MinimalSourceFile } from "../../utils/minimalSourceFile";
 
 /**
@@ -105,11 +103,8 @@ export class PackagePlugin extends ConverterComponent {
         const project = context.project;
         if (this.readmeFile) {
             const readme = readFile(this.readmeFile);
-            const comment = parseComment(
-                lexCommentString(readme),
-                context.converter.config,
-                new MinimalSourceFile(readme, this.readmeFile),
-                context.logger
+            const comment = context.converter.parseRawComment(
+                new MinimalSourceFile(readme, this.readmeFile)
             );
 
             if (comment.blockTags.length || comment.modifierTags.size) {

src/lib/converter/plugins/SourcePlugin.ts

@@ -50,7 +50,7 @@ export class SourcePlugin extends ConverterComponent {
         this.listenTo(this.owner, {
             [Converter.EVENT_END]: this.onEnd,
             [Converter.EVENT_CREATE_DECLARATION]: this.onDeclaration,
-            [Converter.EVENT_CREATE_SIGNATURE]: this.onDeclaration,
+            [Converter.EVENT_CREATE_SIGNATURE]: this.onSignature,
             [Converter.EVENT_RESOLVE_BEGIN]: this.onBeginResolve,
         });
     }
@@ -101,6 +101,31 @@ export class SourcePlugin extends ConverterComponent {
         }
     }
 
+    private onSignature(
+        _context: Context,
+        reflection: Reflection,
+        sig?:
+            | ts.SignatureDeclaration
+            | ts.IndexSignatureDeclaration
+            | ts.JSDocSignature
+    ) {
+        if (this.disableSources || !sig) return;
+
+        const sourceFile = sig.getSourceFile();
+        const fileName = sourceFile.fileName;
+        this.fileNames.add(fileName);
+
+        const position = ts.getLineAndCharacterOfPosition(
+            sourceFile,
+            sig.getStart()
+        );
+
+        reflection.sources ||= [];
+        reflection.sources.push(
+            new SourceReference(fileName, position.line + 1, position.character)
+        );
+    }
+
     /**
      * Triggered when the converter begins resolving a project.
      *

src/lib/converter/utils/repository.ts

@@ -71,7 +71,7 @@ export class Repository {
 
         for (let i = 0, c = repoLinks.length; i < c; i++) {
             let match =
-                /(github(?:\.[a-z]+)*\.[a-z]{2,})[:/]([^/]+)\/(.*)/.exec(
+                /(github(?!.us)(?:\.[a-z]+)*\.[a-z]{2,})[:/]([^/]+)\/(.*)/.exec(
                     repoLinks[i]
                 );
 
@@ -82,6 +82,16 @@ export class Repository {
                 );
             }
 
+            // Github Enterprise
+            if (!match) {
+                match = /(\w+\.ghe.com)[:/]([^/]+)\/(.*)/.exec(repoLinks[i]);
+            }
+
+            // Github Enterprise
+            if (!match) {
+                match = /(\w+\.github.us)[:/]([^/]+)\/(.*)/.exec(repoLinks[i]);
+            }
+
             if (!match) {
                 match = /(bitbucket.org)[:/]([^/]+)\/(.*)/.exec(repoLinks[i]);
             }

src/lib/output/themes/default/templates/reflection.tsx

@@ -71,6 +71,7 @@ export function reflectionTemplate(context: DefaultThemeRenderContext, props: Pa
                                 context.parameter(props.model.indexSignature.type.declaration)}
                         </section>
                     )}
+                    {!props.model.signatures && context.memberSources(props.model)}
                 </>
             )}
             {!!props.model.children?.length && context.index(props.model)}

src/test/Repository.test.ts

@@ -46,6 +46,32 @@ describe("Repository", function () {
             equal(repository.type, RepositoryType.GitHub);
         });
 
+        it("handles a ghe.com URL", function () {
+            const mockRemotes = [
+                "ssh://org@bigcompany.ghe.com/joebloggs/foobar.git",
+            ];
+
+            const repository = new Repository("", "", mockRemotes);
+
+            equal(repository.hostname, "bigcompany.ghe.com");
+            equal(repository.user, "joebloggs");
+            equal(repository.project, "foobar");
+            equal(repository.type, RepositoryType.GitHub);
+        });
+
+        it("handles a github.us URL", function () {
+            const mockRemotes = [
+                "ssh://org@bigcompany.github.us/joebloggs/foobar.git",
+            ];
+
+            const repository = new Repository("", "", mockRemotes);
+
+            equal(repository.hostname, "bigcompany.github.us");
+            equal(repository.user, "joebloggs");
+            equal(repository.project, "foobar");
+            equal(repository.type, RepositoryType.GitHub);
+        });
+
         it("handles a Bitbucket HTTPS URL", function () {
             const mockRemotes = [
                 "https://joebloggs@bitbucket.org/joebloggs/foobar.git",

src/test/converter/comment/specs.json

@@ -99,6 +99,14 @@
               "kind": 2048,
               "kindString": "Method",
               "flags": {},
+              "sources": [
+                {
+                  "fileName": "comment.ts",
+                  "line": 77,
+                  "character": 4,
+                  "url": "typedoc://comment.ts#L77"
+                }
+              ],
               "signatures": [
                 {
                   "id": 22,