KDoc fixes for IntelliJ 2024.X #613
Conversation
# Conflicts: # core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt # core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt
Jolanrensen
changed the title
|
@zaleslaw @koperagen It's ready I think. Although, it might be hard to review. |
|
@Jolanrensen what is the best way to test this? I suppose, looking at the rendering docs, isn't it? |
Yep, and the best way to view those is by letting IntelliJ render them. That works best when the project is published to mavenLocal and you're viewing the source from another project. (Because the generated-sources dir isn't attached as "sources" by intellij, so the highlighting breaks) Actually, it might be awesome if we could see the rendered docs for an entire file while working on it, like the "render all doc comments" button here: |
| public interface PlainDslName | ||
|
|
||
| /** .[**frameCol**][ColumnsSelectionDsl.frameCol] */ | ||
| /** __`.`__[**`frameCol`**][ColumnsSelectionDsl.frameCol] */ |
There was a problem hiding this comment.
How this works? What kind of formatting?
There was a problem hiding this comment.
__ is the same as ** :) so in this case it makes the period bold+code style.
I switched to using __ instead of ** here because:
- kdocs don't like
*at the start. It doesn't always recognize the difference between*indicating the KDoc or*for making stuff bold - If this piece of text is copied over next to something else bold, like
**`singleColumn`**{@include [ColumnGroupName]}, the result would become**`singleColumn`****`.`**[**`frameCol`**]...and break markdown because of the****.
Like this:
singleColumn****.frameCol...
With dashes, instead it becomes**`singleColumn`**__`.`__[**`frameCol`**]...which renders correctly:
singleColumn.frameCol...
| @@ -270,6 +277,7 @@ public fun <T, C> Update<T, C>.with(expression: UpdateExpression<T, C, C?>): Dat | |||
| } | |||
|
|
|||
| /** [Update with][Update.with] to provide a new value for every selected cell giving its row. */ | |||
| @ExcludeFromSources | |||
There was a problem hiding this comment.
What's happened when we exclude this from source? Or all documentation interfaces should be shipped with this annotation?
There was a problem hiding this comment.
Yes, indeed. We should annotate all our documentation interfaces with @ExcludeFromSources. This will exclude them from the sources+compilation and thus shrink the bytecode (in theory). For this PR I started gradually introducing them on a few interfaces already, but far from all of them (#605). There's no rush though, so we can just annotate them whenever we like.
| @@ -53,7 +53,8 @@ internal interface SelectingColumns { | |||
| */ | |||
| interface OperationArg | |||
|
|
|||
| /** {@set [OperationArg] operation} */ | |||
| // Using <code>` notation to not create double `` when including | |||
| /** {@set [OperationArg] <code>`operation`</code>} */ | |||
There was a problem hiding this comment.
We need a table with all our special tricks:))
|
I bumped the docPreprocessor version to 0.3.5 for the project. |
Attempting to fix #585 and some of #605
Cannot fully fix until JetBrains/markdown#150 is merged and inside IntelliJ
This fixes:
` `brackets. Otherwise, the background will not render.` code block `(like that) starts and ends with a space, one surrounding space will be removed. So add one extra like` this `.., are actually code and bold.`block`\n`block`is rendered like`block` `block`, but that again introduces a space that shouldn't be there, so fixing those.something like``this. This can however be avoided by usingcodetagsspanif they are ever rendered correctly.**, alternating with__`tags (Only fixed in grammars for now, as it's invisible in IDE anyways)