Already found a bug in the new version :disappoint...

# dokka

[serebit]

Already found a bug in the new version 😞 https://github.com/Kotlin/dokka/issues/510

[Kamil Doległo]

Sorry to hear that. I’ve proposed a workaround for this issue

[serebit]

I saw, how would I do that in Gradle Kotlin DSL? The docs are a bit ambiguous when it comes to multiplatform configuration in Kotlin DSL.

[serebit]

I'm using multiplatform, just to clarify.

[Kamil Doległo]

You probably want something like

dokka{ 
  multiplatform{
    global{
      perPackageOption{
        prefix = "com.example.internal" 
        suppress = true
      }
    }
  }
}

[Kamil Doległo]

To suppress it on all the platforms

[serebit]

I tried that, but I only get as far as the multiplatform block before I start running into errors. The multiplatform scope doesn't have a member or extension function named global, and using val global by getting also errors. Using val global by creating { does parse successfully, but running the Dokka task errors with List is empty.

[Kamil Doległo]

Yup, it should be val global by creating or register("global") IIRC, but that’s strange. Which version of the Kotlin plugin are you using?

[serebit]

This is what I came up with, and it's the closest I've gotten to succeeding:

tasks.dokka {
    multiplatform {
        val global by creating {
            perPackageOption {
                prefix = "com.serebit.strife.internal"
                suppress = true
            }
        }
    }
}

[serebit]

I'm using 1.3.50.

[serebit]

I can give you a copy of my project if you want to take a look at the configuration. It's multi-module, so the overall configuration is a bit more complex than usual.

[Kamil Doległo]

Sure, I’ve just cloned it from master but if there’s a newer branch I’d like to take a look at it 🙂

[serebit]

Just pushed a new branch dokka-upgrade to origin, link is here: https://gitlab.com/serebit/strife/tree/dokka-upgrade

[serebit]

You should be able to pull it from GitHub too if you cloned it from there.

[Kamil Doległo]

Thanks! Not yet accessible from GH, so I’ll clone it from GitLab

[Kamil Doległo]

Oh, yes

[Kamil Doległo]

I see now

[Kamil Doległo]

This bit is correct

[Kamil Doległo]

But you haven’t defined the other platforms 🙂

[Kamil Doległo]

So, you probably want something like:

tasks.dokka {
    multiplatform {
        val global by creating {
            perPackageOption {
                prefix = "com.serebit.strife.internal"
                suppress = true
            }
        }
        val jvm by creating {}
    }
}

[Kamil Doległo]

The multiplatform documentation needs an explicit list of platforms to document. We could probably change that to use all by default. I don’t know why I did it this way TBH

[Kamil Doległo]

And we need a better error message than “List is empty” for sure

[serebit]

Ah, perfect, thank you! I would definitely appreciate Dokka using all platforms by default, but this works in the interim 🙂

[Kamil Doległo]

Glad I could help 😉

[Kamil Doległo]

Sidenote: If you only document one platform (like jvm here), you don’t need the global block. You can put the perPackageOption block inside the jvm one:

val jvm by creating {
//here
}

It changes nothing but looks better IMHO

[serebit]

If I could grab you for one more thing, there's a couple odd errors that Dokka spits out with a fixed configuration. I'll push a fixed version in a minute so you can take a look. It's one of the classic Can't find node by signature warnings, but the property that the node references is public, and doesn't use any dependencies.

[serebit]

Just pushed the commit to the dokka-upgrade branch.

[Kamil Doległo]

I see that. Honestly, I don’t know why that happens (I wasn’t working on the link resolution for this release), that’s the bad news

[Kamil Doległo]

The good news is: I have yet another workaround for that 😉
you have to reference it like so: Title.text

[serebit]

Excellent! Thank you! That'll be all 🙂

[Kamil Doległo]

Anytime 😉

[serebit]

I lied, one more thing (hopefully last). I have another branch with an additional module, which has references in kdoc to the client module. All of these references are failing to be resolved. What could be causing this?

[serebit]

Ah, I see the FAQ section, never mind. Little disappointing that there isn't an easier way to fix this, but I'll take it 🙂

[Kamil Doległo]

Since this bug with the param that you showed me, I’m no longer sure 😛
I suspect that it’s caused by not having the client module on the classpath of the other one, but I could look into that if you push the branch to the repo

[serebit]

That's probably what it is. Branch pushed, it's commands

[serebit]

Yep, client module wasn't on the classpath. Got it fixed.

[Kamil Doległo]

Yup, that’s exactly the case. We plan to change somehow it in the future releases

[Kamil Doległo]

Next sidenote: There’s a new option that you can probably use (although I don’t know if you want it to be this way)
If you want to get a merged documentation for this command and client modules, you can do something like this:
1) apply the dokka and kotlin plugins in the root directory of the project
2) in the root build.gradle.kts file (where you enabled those plugins) configure dokka accordingly:

tasks.dokka {
    outputDirectory = "$rootDir/public/docs"
    subProjects = listOf("client", "commands")
    multiplatform {
        register("jvm") {}
        register("common") {
            targets = listOf("jvm")
        }
    }
}

[Kamil Doległo]

You’ll probably want the perPackageOption somewhere here also

[Kamil Doległo]

What this does is it extracts the sources from the subprojects called “client” and “command”, from platforms “jvm” and “common” and sort of renames the “common” platform as “jvm” to have it merged with the actual “jvm” platform 😛

[Kamil Doległo]

Hi @serebit!
During fixing your bug with those packages visible, I’ve discovered there’s an easy fix, you just have to add
skipEmptyPackages = true
to each passConfiguration 😉

[serebit]

Oh, sweet, thanks!