Hello! I've just tried dokka plugin MathJax. I hav...

# dokka

[Gleb Minaev]

Hello! I've just tried dokka plugin MathJax. I have a docstring with 2 formulas and I tried to place @usesMathJax in the begining and in the end of it. In both cases documentation on the page of documented symbol renders great, but not in short description of the symbol: either all documentation or formulas are not rendered respectively. (See images in the thread for details.) Is it feature, bug, or me doing something wrong?

[Gleb Minaev]

image.png,image.png,image.png,image.png

[Grégory Lureau]

Have you inspected the generated html?

[Gleb Minaev]

Well, I don't quite understand what to inspect in the generated html. But I found out there is no presence of MathJax on page with short description: there is no appearance of string "MathJax" on it, but there is a lot of the appearances on page the symbol (including <script> tag that downloads MathJax.js).

[Ignat Beresnev]

Hiya! It's an interesting case 🙂 It's both a bug and not a bug, depending on how you look at it.

There's three things to the explanation:
1. How DocTags are parsed
2. How briefs are rendered
3. How mathjax plugin works
_

DocTags are tags like @author, @return, @otherstring . Doctags usually have some text associated with it - the text that follows the tag.

So if you put @usesMathJax doctag in the beginning of the docstring, the whole docstring will be considered to be its content (until it sees another doctag at least).

If you put usesMathJax at the very end with no text following it, no content will be associated with it.
_

For briefs (short description) the first paragraph is usually taken. In your case, your whole docstring is the first paragraph, that's why you can see it in the brief description by default (without @usesMathJax). Try breaking it a little in order to make brief description really brief.

If @usesMathJax tag with some content is found in brief description, it's not rendered, it's probably too long and has too many details for briefs. But that only concerns text that is put after the tag.
_

Mathjax plugin adds mathjax.js script to the page if it sees that any of the page's direct children use the @usesMathJax tag.

As long as the script is present on the page, all formulas will be rendered, regardless of where you put the doctag.

For brief descriptions, this tag is not in the direct children, but it's a child of another child, so the script is not added by default, that's why some formulas don't render.

_

If you put it all together, you can explain the behaviour you're seeing 🙂

[Ignat Beresnev]

TLDR: not a bug per se, but I agree it's confusing.

What I can suggest is making brief description really brief in your case. Try putting new lines after the first sentence, then you'll have at least some brief description on the page, with formulas inside.

If you want to use formulas in brief description, I'm afraid that's not possible at the moment. It will either not be displayed as a formula or it will be skipped

[Gleb Minaev]

Thank you very much! Now I understand what is going on.

[Vadim Mishenev]

As @Ignat Beresnev said, @usesMathJax is a custom block tag, but it is just a marker to add mathjax.js script to the page. It does not matter where the tag is present on the page and what is a tag body.
Thus
1. Using @usesMathJax at the end of KDoc is preferred.
2. Workaround: To display formulas in brief descriptions, @usesMathJax should be applied in the parent declaration that contains documented declaration with the brief description.
In your case usesMathJax should be used in the KDoc of the property coefficients and the class that has the property.
I hope we will make more convenient using of the mathjax plugin in the future to avoid the non obvious configuration .

/**
 * Some text
 * @usesMathJax
 */
class Math() {

    /**
     * Some text: \(a^2 = b^2 + c^2\)
     *
     * Some text
     * @usesMathJax
     */
     val coefficients: List<Double> = emptyList()
}