Hello team, I am trying to customise our dokka us...

# dokka

[Lukas K-G]

Hello team,

I am trying to customise our dokka usage a bit to make it more usable for our customers.

Here are a few things I am trying to achieve:
1. bring back constructor arguments for enum entries ref where it got removed
2. have the arguments of the entries appear in the search
3. insert an additional page that collects information from multiple pages into a single, more concise collections.
I am trying to achieve above by writing a custom plugin, which I managed to set up for basic functionality thanks to the help of the available documentation. 🎉
I am now struggling mainly with extracting the constructor arguments from the enum entries. My understanding is that this would have to happen in DefaultSymbolToDocumentableTranslator as this seems to be the only place that still has access to this kind of information but it does not seem to be extendible by plugins without having to copy/rewrite the whole thing.

Would someone have any suggestions as to how this could be achieved?

[Lukas K-G]

Is it more feasible to "pipe" in the information in form of a separate file maybe? 🤔

[Lukas K-G]

I made some good progress with adding the search key words and rendering the values on the pages. I am still lacking a clean way to extract the values. It doesn't seem like there is an extension point or access to the kotlin analysis though.

[Oleg Yukhnevich]

Hey!
DefaultSymbolToDocumentableTranslator is not accessible by plugins, that's right, and we have no plans to expose access to underlying Kotlin analysis functionality in Dokka
Could you maybe describe a bit why you need to bring back constructor arguments for enum entries?

[Lukas K-G]

Thanks for the insights!
It's basically the discussion from this PR,
TLDR we use enums with values for our error/warning codes and want the value to be discoverable for customers through dokka.
I understand that this is a quite specific requirement hence I am happy to write a custom plugin for this, I just can't seem to easily access the required information from a dokka plugin.

[Oleg Yukhnevich]

Thanks! Now I get it.
Unfortunately, it's not possible to do it directly with Dokka, and I'm not sure that there will be a possibility to include this information somehow in our model or access the underlying analysis APIs

I don't really have any other easy way to get those values besides somehow additionally parsing them from Kotlin sources using the same analysis API. So the only suggestion could be to write the error code directly in the kdoc of the enum entry 😞

[Lukas K-G]

Ok, that saves me some further searching.
We already manually add the value to kdoc, discoverabiliy is limited though.
I guess we will have to generate a md file with the data, probably with ksp and then include it as e.g. package documentation. I was hoping I could avoid the additional complexity.
I might still use a plugin for the search entries though, this works quite nice.

[Lukas K-G]

Actually, would there be a straight forward way to get the values out of the documentable if we already have it in kdoc? I would assume this would work.

[Oleg Yukhnevich]

Yeah, you should have access to documentation field from documentable.
Or you can have a custom tag like @code 1111 and have a custom tag handler

[Lukas K-G]

Custom tag sounds interesting, I'll have a look.

[Lukas K-G]

I further looked into the custom tags and it seems to do mostly what I want.
One question remains though: It seems like when writing a CustomTagContentProvider the contentForBrief content is not included in the enums Entries section even though the documentation on the CustomTagContentProvider.DocumentableContentBuilder.contentForBrief indicates it should:

Brief comment section, usually displayed as a summary/preview.
For instance, when listing all functions of a class on one page, it'll be too much to display complete documentation for each function. Instead, a small brief is shown for each one (i.e the first paragraph or some other important information) - the user can go to the dedicated page for more details if they find the brief interesting.
Tag-wise, it would make sense to include Since Kotlin, since it's important information for the users of stdlib. It would make little sense to include @usesMathjax here, as this information seems to be more specific and detailed than is needed for a brief.

Looking at the code that (I think) generates the briefs, it seems like the custom tags don't seem to be included in the brief:
https://github.com/Kotlin/dokka/blob/62dc1f8e42437ae456674314f3f229f010235814/dokk[…]ains/dokka/base/translators/documentables/DefaultPageCreator.kt
This seems slightly counter intuitive but I might be missing something. Do you have some context why that might be the case?

[Oleg Yukhnevich]

Custom tag brief content is handled separately
But I do see right now that we don't call the contentForCustomTagsBrief for enum entries and constructors - and so custom tags are not rendered there 😞
This feels inconsistent and looks like a bug. Do you mind creating a PR to fix this? 🙂

[Lukas K-G]

Thanks for having a look, I'll create a an according ticket. 🙇

[Lukas K-G]

https://github.com/Kotlin/dokka/issues/4255

[Oleg Yukhnevich]

Do you think that you will be able to create a PR with a fix? I will try to help where possible 🙂

[Lukas K-G]

I can't promise this unfortunately, let's see if I find a free minute. 🙈

[Lukas K-G]

I gave it a shot, feedback is very welcome, especially the unit test node assertion DSL gave me a hard time as the page tree is like 10 nodes deep and super long. https://github.com/Kotlin/dokka/issues/4255