UI improvements

[IgnatBeresnev]

An umbrella issue for many small UI improvements that are planned for the near future. Since most of them are really small and easy to do, I think creating separate issues for each one is excessive.

Emoji statuses to keep track of progress:

• ⌛ Not started
• 👀 In progress / being investigated
• ✔️ Done

Tasks:

• ✔️ For package level pages stop writing it’s package as it’s too long, takes too much space and, actually, there is a package on the top. Write something like “package level declarations” instead (Replace package name on cover with "Package-level declarations" #2586)
• Don’t underline type parameters and functions names that refer to the same page, see findAnnotationOnBean() Won't fix, too much work required for this change
• ✔️ “See also” section: make it the same as Authors & Since section, fix size & alingment. Fix references, see getBean() (Apply the same style to all KDoc tags, including throws/see/parameters #2587)
• ✔️ “Throws” section: make it the same as Authors & Since section, fix references, see decodeFromJsonElement() (Apply the same style to all KDoc tags, including throws/see/parameters #2587)
• ✔️ Make Authors/Since/See also/Throws sections smaller, remove extra indents (Apply the same style to all KDoc tags, including throws/see/parameters #2587)
• ✔️ Drop copy signature functionality at all (Disable copy button for signatures #2577)
• ✔️ Save position in navigation tree (Add auto-scrolling to selected navigation item on page load #2575)
• ✔️ Try to add icons into navigation tree (Add member icons to navigation menu #2578)
• ✔️ Sources: link to sources should be near its signature, we should try to remove source tab from the bottom of a page completely as it’s not intuitive and have problems with MPP, see awaitAll() (Move source links into signatures #2467)
• ✔️ Make current breadcrumb element not clickable and of default font color (Make current breadcrumb element not clickable and of default font color #2588)
• ✔️ Make tab choice between platforms similar to something like on kotlinlang: see Dispatchers and how it’s done on kotlinlang for Kotlin / Groovy tabs: https://kotlinlang.org/docs/gradle.html#plugin-and-versions (Style section and platform tabs like on kotlinlang.org #2589)
• ✔️ Nested/Inner classes should have separate pages and should be present in the navigation tree (Render nested classlikes in navigation #2597)
• ✔️ Add some lines between overloads to separate them better? See getBean (Add a distinct divider between function overloads #2585)
• ✔️ If there's definition only for common platform with no dependencies, there should be no platform tab in package overview. Example (Do not render platform tabs for common-only content #2613)
• ✔️ Don’t cross out deprecated methods, just render @deprecated annotation instead (probably, with ReplaceWith but need to check it), see AnnotationConfigApplicationContext
  • UPD: render a section related to deprecation instead of the annotation itself (Add deprecation details block to pages and strike such pages in navigation #2622)
• ✔️ Display inherited extensions (Display inherited extensions #2625)
• 👀 Enum entries should not have separate pages generated for them, should also be removed from the navigation tree
• ⌛ Drop left column with symbol names completely! Leave only full signatures with their descriptions (see screenshot): it will fix problems with indentation & alignment
• ✔️ Better formatting of declarations with long signatures: currently, a lot of signatures could look better if their parameters were on separate lines (Wrap long signatures dynamically based on taken client width #2659)

Internal feedback:

• ✔️ Constructors for annotation classes should be ignored and not visible in documentation, example (Do not render constructor pages and blocks and for annotation classes #2642)
• ✔️ Parameter names in "Parameters" block should be underlined the same way as links (or styled some other way to be noticable), example (Underline @param tag key for more consistency #2643)
• ✔️ Enum classes should have values() and valueOf() methods (now marked as obvious and ignored), with documentation. Documentation should either be hardcoded in Dokka itself or be taken from some descriptor/sources. (Add documentation for synthetic Enum values() and valueOf() functions #2650)
• ✔️ Clicking on copy link button (anchor) should trigger a popoup with text "Link copied to clipboard" - this is implemented, but for some reason does not work. Search for the popup text to find where exactly (Fix anchor copy button popup #2644)

[IgnatBeresnev]

Pretty much all planned and major improvements have been shipped in 1.7.20, so I'm closing the issue as complete.

---

There are two improvements that did not make it into the release:

Enum entries should not have separate pages generated for them, should also be removed from the navigation tree

Two problems were encountered:

1. If enum entries are removed from the navigation tree, auto-scrolling implemented in Add auto-scrolling to selected navigation item on page load #2575 fails with errors as soon as you load an entry's page, as it does not know to which element to scroll. It needs to be scrolled to the containing enum, but this logic is yet to be implemented.
2. If no pages are generated for enum entries, it could break external documentation links, where a link leads to the enum entry page that does not exist. Moreover, if there's no page, there needs to be a way to link to a specific entry - probably with anchors.

As it requires considerably more time than anticipated, this improvement has been postponed.

Drop left column with symbol names completely! Leave only full signatures with their descriptions (see screenshot): it will fix problems with indentation & alignment

Some prototypes were implemented and it became apparent that it requires some design work as without the left column, declarations are more difficult to distinguish and tend to blend.