Kotlin / dokka

API documentation engine for Kotlin
https://kotl.in/dokka
Apache License 2.0
3.44k stars 410 forks source link

kdoc parser fails when there is a newline inside link/img text. #3661

Open owengray-google opened 4 months ago

owengray-google commented 4 months ago

If you have link text that is very long and splits onto multiple lines, like this, the kdoc parser does not recognize it as a link. We have run into this because ktfmt (https://github.com/facebook/ktfmt) is now formatting our kdoc syntax, producing the diff in this link. In the general case, like this link itself, I don't think it is viable to always require the link be on one line.

The CommonMark spec for markdown explicitly allows line breaks inside link text, and specifies that img tags use a superset of the link syntax.

unnamed (1)

owengray-google commented 3 months ago

Curiously, it appears that inline doc comments on property parameters use a different system, in which this somewhat works:
(However, note that the hoverover text on the 'working' picture is assist chip * image. This is probably a separate bug.)

Screenshot 2024-07-11 at 4 42 02 PM Screenshot 2024-07-11 at 4 23 26 PM
vmishenev commented 3 weeks ago
  1. A breakline is supported for an inline markdown link to an element in IDE and Dokka:

    /**
    * Text
    * [some 
    * link](https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png)
    *
    * Text:
    * [some
    *  text][f]
    */
    fun f() = 0

    IDE: image

    1. External links/image links do not support a breakline due to the lexer grammar here. In the example above, the PSI MARKDOWN_INLINE_LINK tag is [some\n * link](https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png). Then a CommonMark parser processes it as a list item.

    Note! It can work in the case of formatting like in the example with doc comments on property parameters :

image vs

image

In the class A, a tag is [some\n * img(https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png) instead of [some\n * img](https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png)