Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Incorrect handling of the @ symbol in the preformatted text. #1218

Closed
canonic-epicure opened this issue Feb 25, 2020 · 5 comments · Fixed by dbartholomae/redux-dynamic-modules-beacon#25 or gpicron/ssb-subjective-group#1
Labels
bug Functionality does not match expectation

Comments

@canonic-epicure
Copy link
Contributor

If the preformatted text in the docs includes @ symbol (commonly used in decorators):

 * Note, that due to this [issue](https://github.com/Microsoft/TypeScript/issues/7342), if you use decorators in your mixin class,
 * the declaration needs to be slightly more verbose (can not use compact notation for the arrow functions):
 *
 *     class Mixin2 extends Mixin(
 *         [ Mixin1 ],
 *         (base : AnyConstructor<Mixin1, typeof Mixin1>) => {
 *             class Mixin2 extends base {
 *                 @decorator
 *                 prop2 : string
 *             }
 *             return Mixin2
 *         }
 *     ){}
 *

The generated docs looks like this:

image

@canonic-epicure canonic-epicure added the bug Functionality does not match expectation label Feb 25, 2020
@canonic-epicure
Copy link
Contributor Author

Surprisingly when importing the external md file with [[include:BasicFeatures.md]] the result is correct:

image

@Gerrit0
Copy link
Collaborator

Gerrit0 commented Feb 26, 2020

That works because importing files happens after parsing for tags.

Workaround: Use backtick code fences instead of indentation for code blocks. We do have correct handling for fenced code blocks - https://github.com/TypeStrong/typedoc/blob/master/src/lib/converter/factories/comment.ts#L191

@canonic-epicure
Copy link
Contributor Author

Thanks for the info!

@canonic-epicure
Copy link
Contributor Author

Worked well. I guess I'll keep this issue opened for the info can be discovered by others.

@Gerrit0
Copy link
Collaborator

Gerrit0 commented Oct 2, 2021

The fix I put in for this is utterly insufficient.... it assumes everything indented with 4 spaces is code.... which isn't valid if you have a list and put some text on the next line.

/**
 * Text
 * -    List item
 * -    Another list item
 *      This isn't code, but TypeDoc thinks it is
 */

With 0.23, I plan to drop support for indentation based code blocks in TypeDoc's parser. This matches with how TSDoc plans to handle code blocks, and how the vast majority of code is included in the wild (at least based on my manual polling of several projects). Markdown is an incredibly complex language. Trying to support all of these edge cases seems like a bad idea.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Functionality does not match expectation
Projects
None yet
2 participants