Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Kotlin documentation cleanup #206

Closed
cosinekitty opened this issue Apr 24, 2022 · 5 comments
Closed

Kotlin documentation cleanup #206

cosinekitty opened this issue Apr 24, 2022 · 5 comments
Assignees
Labels
documentation Tutorials, explanations, reference documents, etc.

Comments

@cosinekitty
Copy link
Owner

The Dokka tool generates incorrect references to properties. For example, in source/kotlin/doc/-aberration/-corrected/index.md:

//[astronomy](../../../../index.md)/[io.github.cosinekitty.astronomy](../../index.md)/[Aberration](../index.md)/[Corrected](index.md)

# Corrected

[jvm]\
[Corrected](index.md)()

Request correction for aberration.

## Properties

| Name | Summary |
|---|---|
| [name](../../-node-event-kind/-ascending/index.md#-372974862%2FProperties%2F-1216412040) | [jvm]<br>val [name](../../-node-event-kind/-ascending/index.md#-372974862%2FProperties%2F-1216412040): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html) |
| [ordinal](../../-node-event-kind/-ascending/index.md#-739389684%2FProperties%2F-1216412040) | [jvm]<br>val [ordinal](../../-node-event-kind/-ascending/index.md#-739389684%2FProperties%2F-1216412040): [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html) |

It does not make sense to link to NodeEventKind.Ascending from Aberration.Corrected. They are both enums, but they have nothing to do with each other.

I may want to open an issue on the Dokka project, but in the meantime, I will add a cleanup step to the script generate/kotlindoc/format_kotlin_doc.py.

I also want to strip out the [jvm] part.

@cosinekitty cosinekitty self-assigned this Apr 24, 2022
@cosinekitty cosinekitty added the documentation Tutorials, explanations, reference documents, etc. label Apr 24, 2022
@cosinekitty
Copy link
Owner Author

I submitted an issue on the Dokka project for the unwanted Markdown for the name and ordinal properties that link to the wrong class.

@cosinekitty
Copy link
Owner Author

I'm also going to make format_kotlin_doc.py strip out internal enum initializers. For example, it will transform:

[Mars](index.md)(MARS_GM, 686.98, VsopModel(vsopLonMars, vsopLatMars, vsopRadMars))

to

[Mars](index.md)

That stuff is internal code, and should not be exposed as public documentation.

@cosinekitty
Copy link
Owner Author

cosinekitty commented Apr 25, 2022

I found and reported another issue: enum members are listed in backwards order.

@cosinekitty
Copy link
Owner Author

Yet another issue I just reported: documentation includes internal source code for enum constructor calls.

@cosinekitty
Copy link
Owner Author

I made a series of changes to work around these issues, ending with d130405. I think the documentation is in reasonable shape for now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Tutorials, explanations, reference documents, etc.
Projects
None yet
Development

No branches or pull requests

1 participant