warning Encountered an unescaped open brace without an inline tag & warning Unmatched closing brace

[doberkofler]

Search terms

warning Encountered an unescaped open brace without an inline tag
warning Unmatched closing brace

Expected Behavior

No warning

Actual Behavior

./src/components/contacts/index.ts:95:40 - warning Encountered an unescaped open brace without an inline tag
95 * @param {contactData.dataType} [data={}] - The given contact values

./src/components/contacts/index.ts:95:41 - warning Unmatched closing brace
95 * @param {contactData.dataType} [data={}] - The given contact values

Steps to reproduce the bug

export class ContactManagement {
	/**
	 * Constructor for the Contact management object.
	 *
	 * @param {contactData.dataType} [data={}] - The given contact values <--- line 95
	 */
	public constructor(data: contactData.contactValueType = {}) {
        }
}

Environment

• Typedoc version: 0.23.5
• TypeScript version: 4.7.4
• Node.js version: 18.4.0
• OS: maCOS 12.2

[Gerrit0]

This is probably going to be a wontfix. JSDoc's idea of putting default values in the comment was acceptable at the time, but today there are real default values. Just use an initializer instead and remove the redundant initializer from your comment.

Implementing support for this would be horrible, since it essentially means typedoc would have to handle the entire JS grammar.

[doberkofler]

@Gerrit0 I understand but I'm not sure what exactly Just use an initializer instead and remove the redundant initializer means? What would @param {contactData.dataType} [data={}] - The given contact values be supposed to look like?

[Gerrit0]

@param data - The given contact values

The type annotation in your param comment is redundant - you already declared the type in the signature. The same goes for the default value.

TSDoc actually forbids both, but due to the very common use of type annotations, TypeDoc will just silently ignore it. http://typedoc.org/tags/param/#tsdoc-compatibility

[doberkofler]

Thank you for your feedback. I did not know that TypeDoc does not need the type annotations in the comments. Unfortunately this causes a lot of problems and it seems as if only sone comments (like [data={}]) are no longer valid and others still work. I also discovered that only the first warning is shown and once a warning has been fixed the next one is shown. I now changed about 100 of about 2000 that need to be be changed and each time I must rerun typedoc. #1981

[doberkofler]

After having changed the first 100 comments it seems as if "only" the default value of {} would create problems and you might want to consider to at least allow this common use case.

[Gerrit0]

I'd recommend running a workspace search/replace in VSCode, if you search for @param(\s*\{.*\})?\s+\[(.*)=.*\] with regex turned on, you can replace with @param $2 to fix all the issues.

There are many more default values which could cause issues. A few:

/**
 * @param [x="{"]
 * @param [y=`${x}`]
 * @param [z="@bad"]
 */