search

Kotlin / dokka

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

Problems with `package-list` #2775

Open vmishenev opened 1 year ago

vmishenev commented 1 year ago
  1. package-list is in a root folder for a milti-module project, e.g. here. Although in a single module project package-list is in a non-root folder, e.g. here. I agree with Marcin: javadoc places element-list near index.html, like dokka does for multimodule. It can make sense to unify the single module.
  2. You can compare old package-list of stdlib and https://vmishenev.github.io/kotlin-dokka-stdlib/prefinal/stdlib/package-list. The latter has a huge size. I think there are too many redundant $dokka.location commands.
  3. We do not specify cases of using $dokka.location directives explicitly. It would be great to have a doc (e.g. KDoc) describing a package-list format.
hfhbd commented 1 year ago

Another problem: the list is flat: https://github.com/Kotlin/dokka/issues/2444#issuecomment-1100117274

IgnatBeresnev commented 1 year ago

Folks from Google have raised the question of versioning package lists or providing some mechanism that would allow one to understand when package lists have been updated and should be pulled/invalidated.

Use case is the following: build agents don't have access to the internet, so package lists are cached locally and supplied as plain files (as opposed to providing internet URLs). The problem is that it's difficult to understand when external package lists have been updated and thus should be pulled and cached locally.

Note: ETag response header can be used to identify remote resource version. It doesn't help with comparing local package list files (think other formats or transfering files locally), but maybe it'll be enough for the majority of use cases.

IgnatBeresnev commented 1 year ago

Question to consider/research: are there any problems/inaccuracies in package-lists when it comes to KMP code?

IgnatBeresnev commented 1 year ago

Feature to consider, related to package lists: help users understand which package lists are missing.

Use case: you are writing a library and have some Kotlin dependency. By default, types from this dependency will be displayed as plain text (not clickable). However, if you configure an external documentation links for it, types will be resolved (clickable) and will lead to the externally hosted API reference of that library.

How we can help: similar to reportUndocumented, Dokka could report packages/artifacts which are missing package lists, allowing the user to go through the list and provide whatever they can.

This could also boost Dokka's adoption since library authors will want to link to other libraries, and it can help with spreading the word (i.e a library author comes to your repository and asks you to publish Dokka docs so that they can link to it).

hfhbd commented 1 year ago

Reporting unlinked packages would be indeed very nice, but would also require to have a stable link, so you must store the dependency version. Otherwise, your docs point to the wrong (outdated) docs because your dependency released a new update. See also https://github.com/Kotlin/dokka/issues/2443

IgnatBeresnev commented 1 year ago

but would also require to have a stable link, so you must store the dependency version

I think if we were to implement it, we would simply report packages without configured external links. So I see it as Dokka writing something of this nature to the logs:

Undocumented external package: kotlinx.serialization

And then users can go and seek out where external documentation is hosted for kotlinx.serialization.

I understand the problem you're referring to, but I don't see how it would affect this feature. The problem you've mentioned exists already, with or without it, so it should be resolved separately. Unless I don't see the way in which it can interfere

hfhbd commented 1 year ago

Yes, reporting unlinked external packages would work without a stable link, that's right.

However, if you configure an external documentation links for it, types will be resolved (clickable) and will lead to the externally hosted API reference of that library.

I just wanted to add this link can be wrong after a new release.

IgnatBeresnev commented 1 year ago

I just wanted to add this link can be wrong after a new release.

Yeah, that would indeed be a problem if the external documentation is versioned :+1: Thanks for reporting it, btw - I know we didn't react in any way, but we keep this issue mind. It's something that should be fixed, but we don't yet know when as not that many libraries use the versioning plugin (maybe because we need to make it more convinient to set up).

vmishenev commented 1 year ago

Feature to consider, related to package lists: help users understand which package lists are missing.

It was in old Dokka #1470

Use case is the following: build agents don't have access to the internet, so package lists are cached locally and supplied as plain files (as opposed to providing internet URLs). The problem is that it's difficult to understand when external package lists have been updated and thus should be pulled and cached locally.

Is this a practical case? What type of cache do you mean? Can a timestamp help?