Upcoming Typedoc 0.28.2 may break existing `@inline` behavior

[LekoArts]

What package is the bug related to?

typedoc-plugin-markdown

Describe the issue

Hello!

For the issue TypeStrong/typedoc#2923 I've been in contact with the Typedoc maintainer and tried out the current unreleased master branch in my project. With TypeStrong/typedoc@6376273 I'm seeing current and expected behavior of @inline for Returns change.

I think this is somewhat expected since the underlying incoming data is changed now. So I wanted to give you a heads up about this 👍

I'll spend some time today to look into what needs changing.

TypeDoc configuration

I've created a reproduction at https://github.com/lekoarts-demos/typedoc-plugin-markdown-scratchpad/blob/inline-returns-issue/issues/tbd/docs/functions/useExample.mdx

• The comments went missing
• Subsequently the table itself went away

It's now a "Type declaration" and has the information here: https://github.com/lekoarts-demos/typedoc-plugin-markdown-scratchpad/blob/inline-returns-issue/issues/tbd/docs/type-aliases/UseExampleReturn.mdx

Expected behavior

If I run that same example with current released version of Typedoc it looks like this: https://github.com/lekoarts-demos/typedoc-plugin-markdown-scratchpad/blob/inline-returns-issue-old-behavior/issues/tbd/docs/functions/useExample.mdx

So I guess a new table with the new Typedoc version could look like this:

Name	Type	Description
isLoaded	boolean	A boolean that indicates whether Clerk has completed initialization. Initially false, becomes true once Clerk loads.
isSignedIn	boolean | undefined	A boolean that indicates whether a user is currently signed in.
orgRole	string | undefined | null	The current user's role in their active organization.

So a concise version of the Type declaration table, inlined into the one page of useExample

[LekoArts]

When adding a console.log(model) to member.signatureReturns.js, you get these results:

Old:

{ 
  SignatureReflection {
  id: 2,
  name: 'useExample',
  kind: 4096,
  flags: ReflectionFlags { flags: 0 },
  comment: Comment {
    summary: [ [Object] ],
    blockTags: [],
    modifierTags: Set(0) {},
    label: undefined
  },
  variant: 'signature',
  sources: [
    SourceReference {
      fileName: 'issues/tbd/src/index.ts',
      fullFileName: '/Users/lejoe/code/playground/typedoc-plugin-markdown-scratchpad/issues/tbd/src/index.ts',
      line: 64,
      character: 16,
      url: 'https://github.com/lekoarts-demos/typedoc-plugin-markdown-scratchpad/blob/main/issues/tbd/src/index.ts#L64'
    }
  ],
  parameters: [
    ParameterReflection {
      id: 3,
      name: 'initialState',
      kind: 32768,
      flags: [ReflectionFlags],
      comment: undefined,
      variant: 'param',
      defaultValue: '{}',
      type: [IntrinsicType]
    }
  ],
  typeParameters: undefined,
  type: ReflectionType {
    declaration: DeclarationReflection {
      id: 4,
      name: '__type',
      kind: 65536,
      flags: [ReflectionFlags],
      comment: undefined,
      children: [Array],
      documents: undefined,
      childrenIncludingDocuments: [Array],
      groups: [Array],
      categories: undefined,
      variant: 'declaration',
      sources: undefined,
      escapedName: undefined,
      type: undefined,
      typeParameters: undefined,
      signatures: undefined,
      indexSignatures: undefined,
      getSignature: undefined,
      setSignature: undefined,
      defaultValue: undefined,
      overwrites: undefined,
      inheritedFrom: undefined,
      implementationOf: undefined,
      extendedTypes: undefined,
      extendedBy: undefined,
      implementedTypes: undefined,
      implementedBy: undefined,
      typeHierarchy: undefined,
      readme: undefined,
      packageVersion: undefined
    },
    type: 'reflection'
  },
  overwrites: undefined,
  inheritedFrom: undefined,
  implementationOf: undefined
}

New:

{
  SignatureReflection {
  id: 2,
  name: 'useExample',
  kind: 4096,
  flags: ReflectionFlags { flags: 0 },
  comment: Comment {
    summary: [ [Object] ],
    blockTags: [],
    modifierTags: Set(0) {},
    label: undefined
  },
  variant: 'signature',
  sources: [
    SourceReference {
      fileName: 'issues/tbd/src/index.ts',
      fullFileName: '/Users/lejoe/code/playground/typedoc-plugin-markdown-scratchpad/issues/tbd/src/index.ts',
      line: 64,
      character: 16,
      url: 'https://github.com/lekoarts-demos/typedoc-plugin-markdown-scratchpad/blob/main/issues/tbd/src/index.ts#L64'
    }
  ],
  parameters: [
    ParameterReflection {
      id: 3,
      name: 'initialState',
      kind: 32768,
      flags: [ReflectionFlags],
      comment: undefined,
      variant: 'param',
      defaultValue: '{}',
      type: [IntrinsicType]
    }
  ],
  typeParameters: undefined,
  type: UnionType {
    types: [
      [ReflectionType],
      [ReflectionType],
      [ReflectionType],
      [ReflectionType]
    ],
    type: 'union',
    elementSummaries: undefined
  },
  overwrites: undefined,
  inheritedFrom: undefined,
  implementationOf: undefined
}

const typeDeclaration = model.type?.declaration; is undefined then. The types inside UnionType are the correct ReflectionType then again.

[tgreyuk]

@LekoArts thanks for heads-up on this. Will check it out.

[tgreyuk]

Hello,

I have been looking at this. Just wanted to clarify expected output.

So I guess a new table with the new Typedoc version could look like this:

I see your example suggests to merge the unions into a single condensed table. This make sense total sense for this specific example, but I am not sure how feasible such an output is for generic docs where the structure of the unions could be different, and each variant may contain its own comments. This kind of specific implementation is probably better served by custom theme or plugin.

I "think" what the expected behaviour should be (as default) would be to provide a verbose output similar to the type declaration of UseReturnExample that would contain full representation ie?

[LekoArts]

Looking at it with some fresh eyes I think your proposed expected behavior is probably the best for general use case. So far @inline with unions behaved for me like a combination of @interface and @inline (https://typedoc.org/documents/Tags._interface.html). That was fine since I wanted the comments and values to be collapsed.

I've also got your result by copying parts of

typedoc-plugin-markdown/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts

Lines 110 to 128 in e252588

	if (hasTypeDeclaration) {
	if (model.type instanceof UnionType) {
	if (this.helpers.hasUsefulTypeDetails(model.type)) {
	md.push(heading(opts.headingLevel, i18n.theme_type_declaration()));
	model.type.types.forEach((type) => {
	if (type instanceof ReflectionType) {
	md.push(this.partials.someType(type, { forceCollapse: true }));
	md.push(
	this.partials.typeDeclarationContainer(
	model,
	type.declaration,
	options,
	),
	);
	} else {
	md.push(`${this.partials.someType(type)}`);
	}
	});
	}

into the signatureReturns.

Since I don't think that @inline and @interface are supposed to be combined I'll need to do this in a plugin/theme then.

[LekoArts]

Oh, btw, I can use my time during work to put up a PR to add that if that's what we want.

Locally I changed the member.signatureReturns.js to this:

import { heading } from '../../../libs/markdown/index.js';
import { i18n, UnionType, ReflectionType } from 'typedoc';
export function signatureReturns(model, options) {
    const md = [];
    const typeDeclaration = model.type
        ?.declaration;
    const hasTypeDeclaration =
        Boolean(typeDeclaration) ||
        (model.type instanceof UnionType &&
          model.type?.types.some((type) => type instanceof ReflectionType));
    
    md.push(heading(options.headingLevel, i18n.theme_returns()));
    if (!typeDeclaration?.signatures && !hasTypeDeclaration) {
        md.push(this.helpers.getReturnType(model.type));
    }
    const returnsTag = model.comment?.getTag('@returns');
    if (returnsTag) {
        md.push(this.helpers.getCommentParts(returnsTag.content));
    }
    if (typeDeclaration?.signatures) {
        typeDeclaration.signatures.forEach((signature) => {
            md.push(this.partials.signature(signature, {
                headingLevel: options.headingLevel + 1,
                nested: true,
            }));
        });
    }

    if (hasTypeDeclaration) {
        if (model.type instanceof UnionType) {
            if (this.helpers.hasUsefulTypeDetails(model.type)) {
                model.type.types.forEach((type) => {
                    if (type instanceof ReflectionType) {
                        md.push(this.partials.someType(type, { forceCollapse: true }));
                        md.push(
                          this.partials.typeDeclarationContainer(
                            model,
                            type.declaration,
                            options,
                          ),
                        );
                      } else {
                        md.push(`${this.partials.someType(type)}`);
                      }
                })
            }
        }
    }

    if (typeDeclaration?.children) {
        md.push(this.partials.typeDeclaration(typeDeclaration, {
            headingLevel: options.headingLevel,
        }));
    }
    return md.join('\n\n');
}

Is that also what you did?

[tgreyuk]

Hey - yeah basically. I noticed a couple of other bits (missing elementSummary etc).

I will merge what i have done and then you can review it and create another PR if you think anything is missing (if that sounds ok)?

Will then create a patch release with this and your previous PR.

[LekoArts]

aef5620 looks good to me 👍 Thanks! I think you can release as-is :)

[tgreyuk]

available in typedoc-plugin-markdown@4.6.2

[LekoArts]

In case you're curious, I'm trying to add subheadings to the different tables of the union return type via elementSummaries. But it seems like upstream Typedoc doesn't support that: TypeStrong/typedoc#2933

For now I use this in my custom theme (in case someone finds this GitHub issue):

      typeDeclarationUnionContainer: (model, options) => {
        /**
         * @type {string[]}
         */
        const md = [];
        if (model.type instanceof UnionType) {
          const elementSummaries = model.type?.elementSummaries;
          model.type.types.forEach((type, i) => {
            if (type instanceof ReflectionType) {
              const possibleUnionHeadings = model.comment?.getTag('@unionReturnHeadings')
              if (possibleUnionHeadings) {
                if (possibleUnionHeadings.content.length > 0) {
                  const unionHeadings = JSON.parse(this.helpers.getCommentParts(possibleUnionHeadings.content))

                  md.push(heading(3, unionHeadings[i]));
                }
              }

              md.push(this.partials.typeDeclarationContainer(model, type.declaration, options));
            } else {
              md.push(`${this.partials.someType(type)}`);
            }
            if (elementSummaries?.[i]) {
              md.push(this.helpers.getCommentParts(elementSummaries[i]));
            }
          });
        }
        return md.join('\n');
      },

So I can use @unionReturnHeadings to annotate the function. You have to add notRenderedTags: [...OptionDefaults.notRenderedTags, "@unionReturnHeadings"], to your typedoc config.