Add 'name' property to TypeParam and use it in TypeReference.toJavadocURL

[AbdullinAM]

Fix for #3502

[whyoleg]

Probably, we should also add toString here?
In any case, we again broke DRI.toString with these changes.

Something like <$name:${bounds.joinToString(",")}>?
< and > might be needed here to distinguish type parameters from other type references.

[vmishenev]

I do not like that we are breaking package-list. Unlike the previous case, this could break many links.
WDYT about replacing DRI.toString() with a DRI renderer that keeps the old format in DefaultExternalLocationProvider and PackageListService?

[AbdullinAM]

Added custom rendered. We can now, if we want, render varargs as kotlin.Array[*] again, to keep compatibility. Am not sure if this is a good idea though

[whyoleg]

I'm not sure if a custom renderer is a good idea. Now we need to update things in two places. For example, #4347 also changes DRI.toString and so now we need to update toUrlString to be consistent :)

Additionally, I've decided to review a couple of projects package-list files: all projects available on kotlinlang API page, android reference, skiko, ktor, okio, and okhttp. (all checked files package-lists.zip)

And we do print DRI there for two reasons:

1. In case of single module projects (like kotlinx-datetime, skiko, or okio) - because in that case we, for some reason, generate paths, which are not "default" ones for our package-list renderer and resolver.
2. In case we have declarations with the same FQN, but in different source sets - in ktor for js engine, which is shared between js and wasm-js targets, but still have some exposed internals (public declarations) in corresponding source-sets.

And we do have TypeParam usages there:

1. In ktor - but those are internals, so we don't care
2. In kotlinx.datetime - there are some usages in format API, not sure if there will be external usages in libraries for these types, + they will migrate to multi module build and the package-list will not contain those
3. There are 12 usages in okio and 4 usages in skiko. In most cases, those are functions like use/read/write.

So, in the end, I don't think that we will break many links if we change the output of TypeParam.toString, as this only affects package-list compatibility.

---

What I wanted to say is that maybe it's fine to break those links for the sake of consistency. Or, if you think that it's still not a good idea to break them, at least continue to use DRI.toString everywhere and just update TypeParam.toString to be compatible with previous versions (e.g., don't include name there).

[vmishenev]

For example, #4347 also changes DRI.toString and so now we need to update toUrlString to be consistent :)

Do we really need to change it? I'm not going to change it until it breaks something.

By the way, some time ago, it was decided not to rely on .toString and have a mapping logic instead, since

1. .toString can lead to bugs such as Strange internal reference IDs in HTML #2803
2. Non-obvious that .toString is reused in the HTML/package-list renderers directly. From certain perspectives, the Documentable model should not contain rendering logic.

It seems that leaking DRI to HTML/package-list was made by mistake.

[whyoleg]

Do we really need to change it? I'm not going to change it until it breaks something.

I'm not sure I understand. If we don't change it for properties, then we might have an issue where some links will be incorrectly resolved for properties from the package list. Or am I missing something here?

It seems that leaking DRI to HTML/package-list was made by mistake.

Yes, true, and I would expect it might be leaked in more places. That's why I'm a bit concerned that introducing an additional toUrlString with different behavior might do more harm than good at this point.
And so at this point, I would say it will be safer to rely on DRI.toString.

From certain perspectives, the Documentable model should not contain rendering logic.

Yes, but in this case, I think it's not about rendering per se, but rather about some constant identifier, and in this case, DRI and its DRI.toString is this identifier, and it should be fine to rely on it in rendering.

---

At this point, I would really suggest that we just update TypeParam.toString to return the same string as before ("TypeParam(bounds=[$bounds])", without name property) and discuss DRI.toString usage in HTML/package-list separately.

[AbdullinAM]

Yes, I think that is the best resolution in terms of the current PR.

I will create a separate issue for the usage of DRI.toString in HTML/package-lists

[AbdullinAM]

#4353

[vmishenev]

we might have an issue where some links will be incorrectly resolved for properties from the package list. Or am I missing something here?

If we have .toUrlString , we won’t have any issues resolving properties from the package list.
Since we decided to keep DRI.toString, I am going to restore the old version of DRI.toString in #4347

DRI and its DRI.toString is this identifier, and it should be fine to rely on it in rendering.

This is debatable. There are different points of view. For example, the previous one is not mine)

[whyoleg]

Since we decided to keep DRI.toString, I am going to restore the old version of DRI.toString in #4347

Please then also mention it in #4353, as I thought that in #4347 we are changing DRI.toString intentionally, e.g., distinguishing property vs function in package-list too.