nlepage / typedoc-plugin-resolve-crossmodule-references Goto Github PK

View Code? Open in Web Editor NEW

6.0 2.0 2.0 1.47 MB

TypeDoc plugin for resolving cross module reference in a mono-repository

License: Apache License 2.0

TypeScript 100.00%

typedoc-plugin typedoc monorepo

typedoc-plugin-resolve-crossmodule-references's Introduction

Deprecated

Good news, since TypeDoc v0.24.0 this plugin isn't necessary anymore.

Documentation

TypeDoc plugin to resolve cross-module references in a mono-repository.

See issue 1835 at TypeDoc.

Example of generated documentation with this plugin.

typedoc-plugin-resolve-crossmodule-references's People

Contributors

Stargazers

Watchers

Forkers

whenderson boneskull

typedoc-plugin-resolve-crossmodule-references's Issues

checkTyped should be recursive

The checkTyped function currently only works against root types (raw Array and reference).
Should also (I'm sure there would be a comprehensive list somewhere, but these are the ones I found) support:

union
array
intrinsic
reflection
conditional
mapped
inferred
typeOperator
indexedAccess
literal
query
tuple
rest
intersection

I'm not familiar enough with the TypeScript AST or TypeDoc to know where these objects are coming from, but I would hope there may be some form of pre-built visitor function to avoid special casing everything?

If it helps, this is what I hacked together whilst debugging:

function recursiveFixType(context, type) {
    if (!type)
        return type;

    if (type.type === 'union') {
        recursiveFixType(context, type.types);
    }
    else
    if (type.type === 'array') {
        console.debug(type?.type);
        type.elementType = recursiveFixType(context, type.elementType);
    }
    else
    if (type.type === 'intrinsic') {
        console.debug(type?.type);
    }
    else
    if (type.type === 'reflection') {
        console.debug(type?.type);
    }
    else
    if (type.type === 'conditional') {
        console.debug(type?.type);
        type.checkType = recursiveFixType(context, type.checkType);
        type.extendsType = recursiveFixType(context, type.extendsType);
        type.trueType = recursiveFixType(context, type.trueType);
        type.falseType = recursiveFixType(context, type.falseType);
    }
    else
    if (type.type === 'mapped') {
        console.debug(type?.type);
        type.parameterType = recursiveFixType(context, type.parameterType);
        type.templateType = recursiveFixType(context, type.templateType);
        type.nameType = recursiveFixType(context, type.nameType);
    }
    else
    if (type.type === 'inferred') {
        console.debug(type?.type);
    }
    else
    if (type.type === 'typeOperator') {
        console.debug(type?.type);
        type.target = recursiveFixType(context, type.target);
    }
    else
    if (type.type === 'indexedAccess') {
        console.debug(type?.type);
        type.objectType = recursiveFixType(context, type.objectType);
        type.indexType = recursiveFixType(context, type.indexType);
    }
    else
    if (type.type === 'literal') {
        console.debug(type?.type);
    }
    else
    if (type.type === 'query') {
        console.debug(type?.type);
        type.queryType = recursiveFixType(context, type.queryType);
    }
    else
    if (type.type === 'tuple') {
        console.debug(type?.type);
        recursiveFixType(context, type.elements);
    }
    else
    if (type.type === 'rest') {
        console.debug(type?.type);
        type.elementType = recursiveFixType(context, type.elementType);
    }
    else
    if (type.type === 'intersection') {
        console.debug(type?.type);
        recursiveFixType(context, type.types)
    }
    else
    if (Array.isArray(type)) {
        type.forEach(
            (inner_type, i) => {
                type[i] = recursiveFixType(context, inner_type);
            }
        );
    }
    else
    if (isReferenceType(type)) {
        recursiveFixType(type.typeArguments);
        type = fixType(context, type);
    }
    else {
        console.debug('unexpected type:', type?.type);
    }
    return type;
}

Broken package

I think the package sent to npm is broken.

Error: The plugin typedoc-plugin-resolve-crossmodule-references could not be loaded.
Error: Error: Cannot find module '.../node_modules/typedoc-plugin-resolve-crossmodule-references/dist'. Please verify that the package.json has a valid "main" entry

Whe you look in node_modules/typedoc-plugin-resolve-crossmodule-references there is no dist folder.

I found this plugin whilst reviewing Cross-package references in monorepository not working #1835

findSymbolSourceFile reliant on source maps.. which don't seem to be present

const srcMapConverter = fromSource(declSrcFile.text) ?? fromMapFileSource(declSrcFile.text, srcDirPath)
returns null for me. It seems that source maps are not being generated for me.

Either way, I'm not sure they are necessary.
I replaced the logic with:

        const declSrcFile = declaration.getSourceFile();
        const declSrcFileName = declSrcFile.fileName;
        const srcFile = project.files.find(({ fullFileName }) => fullFileName === declSrcFileName);
        if (!srcFile)
            continue;
        return srcFile;

and it seems to be working fine.

I'm probably missing something important but just wanted to get something working.

Still getting `XXX is referenced by YYY but not included in the documentation.`

Hello @nlepage ,
I tried to use your plugin for crosslinks between packages, but unfortunately it doesn't work as the usual warnings appear.
My environment is that:

    "typedoc": "^0.23.16",
    "typedoc-plugin-resolve-crossmodule-references": "^0.3.1",
    "typescript": "4.7.4"

and I am using

$ npx typedoc --plugin typedoc-plugin-resolve-crossmodule-references  --entryPointStrategy packages packages/*

to build the documentation.

Let me know if I can do further tests to understand where the problem is.

Generic type defaults dont seem to be mapped

came across this issue while using this plugin,

If I have:
export function someFunction<T extends ISomething= ISomething>

where ISomething is from a different module I get:

warning ISomething is referenced by someFunction but not included in the documentation

It looks like its only the default value thats not mapped to the new module, because this definition:

export function someFunction<T extends ISomething>

compiles ok.

link doesn't work when implementing an interface

The plugin isn't working for implement. Like I'm implementing an interface from another package of the monorepo and it's breaking. repro: imranbarbhuiya/TagScript#53

line: https://github.com/imranbarbhuiya/TagScript/blob/b77fe5e98f018f1ffe8925ad840088a012bec903/packages/tagscript-plugin-discord/src/lib/Parsers/Cooldown.ts#L24

TypeError: type.getSymbol is not a function

TypeDoc 0.24.6
typedoc-plugin-resolve-crossmodule-references 0.3.3

yarn run v1.22.19
$ typedoc
[info] Loaded plugin typedoc-plugin-resolve-crossmodule-references
[info] Converting project at ./packages/api-types
TypeDoc exiting with unexpected error:
TypeError: type.getSymbol is not a function
    at isReferenceTypeBroken (E:\_DisCloud\discloud.app\node_modules\typedoc-plugin-resolve-crossmodule-references\dist\index.js:149:44)
    at fixType (E:\_DisCloud\discloud.app\node_modules\typedoc-plugin-resolve-crossmodule-references\dist\index.js:104:34)        
    at fixTyped (E:\_DisCloud\discloud.app\node_modules\typedoc-plugin-resolve-crossmodule-references\dist\index.js:100:24)       
    at Object.conditional (E:\_DisCloud\discloud.app\node_modules\typedoc-plugin-resolve-crossmodule-references\dist\index.js:34:13)
    at Object.conditional (E:\_DisCloud\discloud.app\node_modules\typedoc\dist\lib\models\types.js:71:34)
    at ConditionalType.visit (E:\_DisCloud\discloud.app\node_modules\typedoc\dist\lib\models\types.js:42:36)
    at recursivelyFixTyped (E:\_DisCloud\discloud.app\node_modules\typedoc-plugin-resolve-crossmodule-references\dist\index.js:87:20)
    at visitReflection (E:\_DisCloud\discloud.app\node_modules\typedoc-plugin-resolve-crossmodule-references\dist\index.js:14:9)  
    at Converter.<anonymous> (E:\_DisCloud\discloud.app\node_modules\typedoc-plugin-resolve-crossmodule-references\dist\index.js:9:82)
    at triggerEvents (E:\_DisCloud\discloud.app\node_modules\typedoc\dist\lib\utils\events.js:196:43)
error Command failed with exit code 6.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Generic support

Hi!
i have a code like:
packages/base/index.ts

export interface List<T> {
  total: number;
  items: T[];
}

packages/other/index.ts

async listEntity(): Promise<List<Entity>>

But in docs i getting:

listEntity(): Promise<List>

Thanks! this plug-in is awesome!

Cross-module references with `@link` are not recognized

Description

As the title says, I think there is a bug that @link cross-modue references are not recognized by the plugin.

Example:

I try to reference a class in another module like this:

@see {@link LiskValidator}
@see {@link Lisk_Validator.LiskValidator}
@see {@link LiskValidationError}
@see {@link Lisk_Validator.LiskValidationError}

As I am new to TypeDoc, it might also be that I am referencing incorrectly, so I tried a few different ways, but none of the above links work.

The rendered result looks like this:

As you can see,under Returns the link it recognized successfully for LiskValidationError, but under See the link is not recognized.

Here is the link to the example:
https://liskhq.github.io/lisk-docs/lisk-sdk/v6/references/typedoc/functions/_liskhq_lisk_transactions.validateTransaction.html