Typedoc should support complex @default values

[ST-DDT]

Search terms

@default, complex object, jsdoc tag

Expected Behavior

Typedoc should support complex @default values.

Actual Behavior

./index.ts:12:10 - warning Encountered an unescaped open brace without an inline tag

12       * uuid({ foo: "bar" })

./index.ts:12:23 - warning Unmatched closing brace

12       * uuid({ foo: "bar" })

It doesn't output the warning, when using an @example tag.
IMO @default refers to a value and thus should behave the same as @example.

Steps to reproduce the bug

import type { ProjectReflection, TypeDocOptions } from "typedoc";
import { Application, TSConfigReader } from "typedoc";

/**
 * Foo.
 */
export function foo(options: {
  /**
   * @example uuid({ foo: "bar" })
   */
  bar: string;
}) {
  return options.bar;
}

function loadProject(
  options: Partial<TypeDocOptions> = {
    entryPoints: ["index.ts"],
    pretty: true,
    cleanOutputDir: true,
  }
): [Application, ProjectReflection] {
  const app = new Application();
  app.options.addReader(new TSConfigReader());
  app.bootstrap(options);
  const project = app.convert();
  app.generateJson(project, "output.json");

  return [app, project];
}

loadProject();

Environment

• Typedoc version: 0.23.28
• TypeScript version: 5.0.3, 4.9.5 (doesn't really matter)
• Node.js version: v18.15.0
• OS: Win10

[Gerrit0]

The @example tag has this special casing because JSDoc made the (bad) decision to state that its contents should be highlighted as code, and it is used to frequently for TypeDoc to make the call that its contents should not be and force people to use the TSDoc specification of the tag

The TSDoc @defaultValue specification examples indicate that arbitrary text should be permitted, not just the value. JSDoc's @default implies that it's just the value.... I think the TSDoc spec is better here. Wrapping stuff that's meant to be code in backticks to actually mark it as code is a good thing.

I really don't want to do this, but wow there are a lot of matches for @default/@defaultValue in DefinitelyTyped which assume the JSDoc interpretation... It's far from universal, and there are a lot of usages which assume it's a string, or isn't actually valid code, but there are enough that I'm leaning towards unhappily agreeing with you. I'd like to move the @example hackery under an option flag as well, so this might be a good excuse to finally get around to doing that....

[ST-DDT]

I'd like to move the @example hackery under an option flag as well, so this might be a good excuse to finally get around to doing that....

I'm not sure how exactly you have planned that, but it might be good to be some kind of list of tags or { [tag]: language } that should be treated as code. That way, it is possible to define custom tags there as well e.g. for i18n keys @translatable foo.bar.xyz {arg1} {arg2}.

[Gerrit0]

I'm not sure I agree with that. Doc comments are meant to be read/rendered with an editor too, and VSCode/other editors won't know that it should be a code block. VSCode doesn't render @default as a code block either (but does @example - sometimes). Adding features which encourage writing docs that don't show up nicely in editors isn't something I want to do.

[ST-DDT]

Default tag:

This looks like code highlighting to me.

Example tag:

This also looks like code highlighting.

Deprecation tag:

Just for reference, when it doesn't show up as code.

rangeToNumber(
    numberOrRange:
      | number
      | {
          /**
           * The minimum value for the range.
           */
          min: number;
          /**
           * The maximum value for the range.
           *
           * @deprecated
           * number({ min: 10 })
           */
          max: number;
        }
  ): number

[Gerrit0]

You're totally right, I was going off memory from when I fixed @example, didn't remember seeing @default in there.