https://kotlinlang.org logo
#dokka
Title
# dokka
e

evanchooly

08/15/2022, 8:21 PM
does dokka not support multiple
@see
entries?
i

Ignat Beresnev

08/15/2022, 8:43 PM
It should Can you give an example of how you're using it?
e

evanchooly

08/15/2022, 8:43 PM
@see [foo] @see [bar] @see [baz]
all that shows up is the final one
this is with 1.7.10
i

Ignat Beresnev

08/15/2022, 8:45 PM
Is
{
instead of
[
intentional or a mistake?
e

evanchooly

08/15/2022, 8:46 PM
oh. a mistake. 🙂 sorry.
i

Ignat Beresnev

08/15/2022, 8:51 PM
Copy code
/**
 * Generic description
 *
 * @see [IllegalStateException] for exception
 * @see [List] for list
 * @see [Map] for map
 */
fun seeDemo() {}
Yeah, should work just fine It'll look a bit better in the next release ;)
e

evanchooly

08/15/2022, 8:52 PM
i guess the difference is i'm trying to refer to other functions as opposed to other types.
e.g., this class has
find()
and
stream()
which are similar but different so i'm trying to cross-reference
(dokka's output/format has come a long way since i last looked. i quite like it especially compared to the recent javadoc formats)
i

Ignat Beresnev

08/15/2022, 8:53 PM
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
e

evanchooly

08/15/2022, 9:09 PM
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)
i'll show you my source and then a screen clip of the rendered bits.
Copy code
/**
     * @see [List] check the listing!
     * @see [Map] paging Lewis and Clark
     * @see [find] find me
     * @see [list] list me
     * @see [stream] stream me
     */
image.png
so as you can see the
List
and
Map
render correctly but the three refs to functions end up only being the last one
(also it would be great if those packages weren't included especially when referring to functions)
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.
i

Ignat Beresnev

08/16/2022, 12:19 PM
Thanks for reporting it, I'll have a closer look today
e

evanchooly

08/16/2022, 2:47 PM
want me to file something on YouTrack?
i

Ignat Beresnev

08/17/2022, 3:55 PM
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
e

evanchooly

08/17/2022, 3:56 PM
perfect. thanks. mine weren't static fwiw but i'm sure it's all related. 🤞🏻
i

Ignat Beresnev

08/17/2022, 3:59 PM
Isn't
PanacheCompanionBase
a
companion object
or just an
object
?
as far as I can see Kotlin doesn't let you import functions otherwise
e

evanchooly

08/17/2022, 4:00 PM
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.
i

Ignat Beresnev

08/17/2022, 5:44 PM
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:
Copy 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 ^ 🙂
e

evanchooly

08/17/2022, 5:45 PM
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. 🙂
🦜 1
i

Ignat Beresnev

08/17/2022, 5:46 PM
JFYI the fix will be released in 1.7.20, and it seems like there's no workaround for now 😞
e

evanchooly

08/17/2022, 7:58 PM
no worries. it's not a rush here. we do releases every 2ish weeks anyway so when .20 lands, we'll get it.
is there a plugin to create a dokka-format jar and attach it to the maven project or should i wire that up manually.
like
javadocJar
but with the dokka format.
i

Ignat Beresnev

08/17/2022, 8:07 PM
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
e

evanchooly

08/17/2022, 8:08 PM
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. 🙂
i

Ignat Beresnev

08/17/2022, 8:14 PM
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 😞
e

evanchooly

08/17/2022, 8:14 PM
oh! that's exactly what I was looking for! 🙂
i thought I'd seen that somewhere but couldn't find it yesterday when I went looking. thanks.
i

Ignat Beresnev

08/17/2022, 8:23 PM
Yeah, it was linked recently by another member in the javadoc.io discussion, props to @Joe for figuring it out 🙂
5 Views