The TypeDoc example

[srmagura]

Closes #1556.

Following are notes / potential issues.

Modules

• I tried using @module to document a module but I couldn't find where that comment appears in the generated documentation. See functions.ts.

Enums

• My doc comment for EnumLikeObject isn't in the generated documentation.
• If you compare the members of StringEnum and EnumLikeObject, you'll notice that StringEnum has double quotes around the values while EnumLikeObject doesn't.
• TypeDoc doesn't show the value of computed members in enums, see CrazyEnum.ComputedMember.

Objects

• I added a doc comment to a property of an as const object but it doesn't appear in the generated documentation. Probably not an issue but thought it worth mentioning. See ObjectConstant.

Markdown

• I wanted my Shakespeare quote (in playground.ts) to be multiple lines, but if you add two spaces to the end of each line, Prettier just removes the spaces. Do you think this is a Prettier bug? I'm not sure if Markdown in doc comments is a first-class use case for them.

Syntax Highlighting

• As I stated in another thread, syntax highlighting is still broken for C# and Razor.
• From what I can tell, the default language for code blocks is typescript. Would it make sense to change it to tsx? The only drawback I can think of is that TSX does not support the old style of type assertions (<number>myVariable) which I don't think anyone uses anymore.

Styles

• On the CancellablePromise page, the vertical space between "This example shows off how TypeDoc handles" and the list is quite large.

[srmagura]

Done! Let me know of any changes you want.

I put a list of comments / issues in the initial comment on the PR.

[Gerrit0]

If you compare the members of StringEnum and EnumLikeObject, you'll notice that StringEnum has double quotes around the values while EnumLikeObject doesn't.

Shoot, this is a bug. It should have quotes too... easy fix at least.

TypeDoc doesn't show the value of computed members in enums, see CrazyEnum.ComputedMember.

This is expected because there's no way to figure out what the constant value is for arbitrary expressions.

Do you think this is a Prettier bug?

Maybe? I didn't even know this was a markdown feature until just now...

syntax highlighting is still broken for C# and Razor.

If you submit a PR to Shiki that just bumps the version, orta will merge it and a new version will be published, which should fix this, assuming it is fixed on main over there...

From what I can tell, the default language for code blocks is typescript. Would it make sense to change it to tsx? The only drawback I can think of is that TSX does not support the old style of type assertions (myVariable) which I don't think anyone uses anymore.

Maybe... It also breaks single-type parameter generic arrow functions. const X = <T>(x: T) => x. The TypeScript playground tripped me up for months when it switched from TS to TSX mode by default...

On the CancellablePromise page, the vertical space between "This example shows off how TypeDoc handles" and the list is quite large.

Yeah... going away in 0.23 or sooner if someone fixes it, which I'd be fine with, this is because right now TypeDoc parses the first paragraph of a comment as the shortText, and puts it in its own block. This has other problems, since it can cause a code block to be split up.

[Gerrit0]

This is looking great! A few comments

[srmagura]

Maybe? I didn't even know this was a markdown feature until just now...

Lol, I will report it to Prettier.

If you submit a PR to Shiki that just bumps the version, orta will merge it and a new version will be published, which should fix this, assuming it is fixed on main over there...

Done, see shikijs/shiki#241.

Maybe... It also breaks single-type parameter generic arrow functions. const X = (x: T) => x. The TypeScript playground tripped me up for months when it switched from TS to TSX mode by default...

Didn't know about that one. Normal typescript is probably the best default then.

[srmagura]

Thanks for the feedback, all changes have been made.

[Gerrit0]

Looks great! Thanks again :) Once the next release is published, I will look at getting this rendering on typedoc.org