does dokka not support multiple `@see` entries?

# dokka

[evanchooly]

does dokka not support multiple @see entries?

[Ignat Beresnev]

It should

Can you give an example of how you're using it?

[evanchooly]

@see [foo]
@see [bar]
@see [baz]

[evanchooly]

all that shows up is the final one

[evanchooly]

this is with 1.7.10

[Ignat Beresnev]

Is { instead of [ intentional or a mistake?

[evanchooly]

oh. a mistake. 🙂 sorry.

[Ignat Beresnev]

/**
 * Generic description
 *
 * @see [IllegalStateException] for exception
 * @see [List] for list
 * @see [Map] for map
 */
fun seeDemo() {}

[Ignat Beresnev]

Yeah, should work just fine

It'll look a bit better in the next release ;)

[evanchooly]

i guess the difference is i'm trying to refer to other functions as opposed to other types.

[evanchooly]

e.g., this class has find() and stream() which are similar but different so i'm trying to cross-reference

[evanchooly]

(dokka's output/format has come a long way since i last looked. i quite like it especially compared to the recent javadoc formats)

[Ignat Beresnev]

Even if the type is not resolved, it should still be present in documentation, just not clickable (i.e not pointing to any specific declaration). Functions should work just the same as types

Could you share a more close to life example and what you're seeing in Dokka's output? To try to reproduce the problem

[evanchooly]

ok. i think i've perhaps isolated the what/where. it looks like it's combining entries with a shared type almost as if being stored in a Map (i know i'm guessing here)

[evanchooly]

i'll show you my source and then a screen clip of the rendered bits.

[evanchooly]

/**
     * @see [List] check the listing!
     * @see [Map] paging Lewis and Clark
     * @see [find] find me
     * @see [list] list me
     * @see [stream] stream me
     */

[evanchooly]

image.png

[evanchooly]

so as you can see the List and Map render correctly but the three refs to functions end up only being the last one

[evanchooly]

(also it would be great if those packages weren't included especially when referring to functions)

[evanchooly]

i can file a formal issue on this so you don't have to rely on slack to keep track of it if you'd like.

[Ignat Beresnev]

Thanks for reporting it, I'll have a closer look today

[evanchooly]

want me to file something on YouTrack?

[Ignat Beresnev]

Hi! I'm able to reproduce it, so no need, you've helped a lot as it is, thanks!

I've created an issue on GitHub with a simple reproducer to keep track: https://github.com/Kotlin/dokka/issues/2626

[evanchooly]

perfect. thanks. mine weren't static fwiw but i'm sure it's all related. 🤞🏻

[Ignat Beresnev]

Isn't PanacheCompanionBase a companion object or just an object?

[Ignat Beresnev]

as far as I can see Kotlin doesn't let you import functions otherwise

[evanchooly]

oh, right. that's a companion object, right. i had it as an interface in my head because some of waves hand in there uses interfaces.

[Ignat Beresnev]

I'm surprised we haven't encountered this before: the function that resolves fully qualified names returns only the class name for all functions and properties that are static or declared in objects. So @see [Collections.emptyList] would be resolved to just @see [Collections]

And of course further down the road there's that piece of code:

<tags>.groupByTo(linkedMapOf()) { it.second.name }

it looks like it's combining entries with a shared type almost as if being stored in a Map (i know i'm guessing here)

So you were quite right here ^ 🙂

[evanchooly]

ha! nice. i hate it when people try to say where/what the bug is but I feel like i've been bitten by this exact thing myself a time or two. 🙂

[Ignat Beresnev]

JFYI the fix will be released in 1.7.20, and it seems like there's no workaround for now 😞

[evanchooly]

no worries. it's not a rush here. we do releases every 2ish weeks anyway so when .20 lands, we'll get it.

[evanchooly]

is there a plugin to create a dokka-format jar and attach it to the maven project or should i wire that up manually.

[evanchooly]

like javadocJar but with the dokka format.

[Ignat Beresnev]

Not that I'm aware of, no

Imho it makes little sense outside jvm platform, and for m2 publishing people usually put Dokka's output inside javadoc.jar. Here's an example

[evanchooly]

ugh. we're a maven shop but i know how to do it all manually in maven. was just hoping I didn't have to. 🙂

[Ignat Beresnev]

I believe you can automate it in maven as well, here's a configuration

Unfortunately, maven support is overall poor in Dokka, with some key features missing 😞

[evanchooly]

oh! that's exactly what I was looking for! 🙂

[evanchooly]

i thought I'd seen that somewhere but couldn't find it yesterday when I went looking. thanks.

[Ignat Beresnev]

Yeah, it was linked recently by another member in the javadoc.io discussion, props to @Joe for figuring it out 🙂