Refactor brief documentation, remove `Parameters` block from functions' pages

5 files changed, 41 insertions, 27 deletions

diff --git a/core/src/main/kotlin/model/Documentable.kt b/core/src/main/kotlin/model/Documentable.kt
index 94bd624a..176647fa 100644
--- a/core/src/main/kotlin/model/Documentable.kt
+++ b/core/src/main/kotlin/model/Documentable.kt
@@ -23,17 +23,6 @@ abstract class Documentable {
         other is Documentable && this.dri == other.dri // TODO: https://github.com/Kotlin/dokka/pull/667#discussion_r382555806
 
     override fun hashCode() = dri.hashCode()
-
-    val briefDocTagString: String by lazy {
-        // TODO > utils
-        documentation.values
-            .firstOrNull()
-            ?.children
-            ?.firstOrNull()
-            ?.root
-            ?.docTagSummary()
-            ?.shorten(40) ?: ""
-    }
 }
 
 data class PlatformDependent<out T>(
diff --git a/core/src/main/kotlin/pages/ContentNodes.kt b/core/src/main/kotlin/pages/ContentNodes.kt
index 6a8ad3b3..414fac4a 100644
--- a/core/src/main/kotlin/pages/ContentNodes.kt
+++ b/core/src/main/kotlin/pages/ContentNodes.kt
@@ -167,7 +167,7 @@ interface Style
 interface Kind
 
 enum class ContentKind : Kind {
-    Comment, Constructors, Functions, Parameters, Properties, Classlikes, Packages, Symbol, Sample, Main
+    Comment, Constructors, Functions, Parameters, Properties, Classlikes, Packages, Symbol, Sample, Main, BriefComment
 }
 
 enum class TextStyle : Style {
diff --git a/core/src/main/resources/dokka/styles/style.css b/core/src/main/resources/dokka/styles/style.css
index 9aa2eb10..5284364b 100644
--- a/core/src/main/resources/dokka/styles/style.css
+++ b/core/src/main/resources/dokka/styles/style.css
@@ -101,6 +101,13 @@ td:first-child {
     font-family:Monaco, Bitstream Vera Sans Mono, Lucida Console, Terminal;
 }
 
+.brief {
+    width: 40vw;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
 h1, h2, h3, h4, h5, h6 {
     color:#222;
 }
diff --git a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
index 390730a3..2af547b8 100644
--- a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
+++ b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
@@ -28,6 +28,7 @@ open class HtmlRenderer(
         pageContext: ContentPage,
         childrenCallback: FlowContent.() -> Unit
     ) = when {
+        node.dci.kind == ContentKind.BriefComment -> div("brief") { childrenCallback() }
         node.style.contains(TextStyle.Paragraph) -> p { childrenCallback() }
         node.style.contains(TextStyle.Block) -> div { childrenCallback() }
         else -> childrenCallback()
diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
index 3fc9592a..b92c058a 100644
--- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
+++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
@@ -4,8 +4,6 @@ import org.jetbrains.dokka.base.signatures.SignatureProvider
 import org.jetbrains.dokka.base.transformers.pages.comments.CommentsToContentConverter
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.*
-import org.jetbrains.dokka.model.Annotation
-import org.jetbrains.dokka.model.Enum
 import org.jetbrains.dokka.model.Function
 import org.jetbrains.dokka.model.doc.TagWrapper
 import org.jetbrains.dokka.pages.*
@@ -45,8 +43,8 @@ open class DefaultPageCreator(
         block("Packages", 2, ContentKind.Packages, m.packages, m.platformData.toSet()) {
             link(it.name, it.dri)
         }
-        text("Index\n")
-        text("Link to allpage here")
+//        text("Index\n") TODO
+//        text("Link to allpage here")
     }
 
     protected open fun contentForPackage(p: Package) = contentBuilder.contentFor(p) {
@@ -61,17 +59,28 @@ open class DefaultPageCreator(
     ) = contentBuilder.contentFor(s as Documentable) {
         block("Types", 2, ContentKind.Classlikes, s.classlikes, platformData.toSet()) {
             link(it.name.orEmpty(), it.dri)
-            +buildSignature(it)
-            text(it.briefDocTagString)
+            group {
+                +buildSignature(it)
+                group(kind = ContentKind.BriefComment) {
+                    text(it.briefDocumentation())
+                }
+            }
         }
         block("Functions", 2, ContentKind.Functions, s.functions, platformData.toSet()) {
             link(it.name, it.dri)
-            +buildSignature(it)
-            text(it.briefDocTagString)
+            group {
+                +buildSignature(it)
+                group(kind = ContentKind.BriefComment) {
+                    text(it.briefDocumentation())
+                }
+            }
         }
         block("Properties", 2, ContentKind.Properties, s.properties, platformData.toSet()) {
             link(it.name, it.dri)
-            text(it.briefDocTagString)
+            group(kind = ContentKind.BriefComment) {
+                text(it.briefDocumentation())
+            }
+
         }
     }
 
@@ -83,8 +92,12 @@ open class DefaultPageCreator(
         if (c is WithConstructors) {
             block("Constructors", 2, ContentKind.Constructors, c.constructors, c.platformData.toSet()) {
                 link(it.name, it.dri)
-                +buildSignature(it)
-                text(it.briefDocTagString)
+                group {
+                    +buildSignature(it)
+                    group(kind = ContentKind.BriefComment) {
+                        text(it.briefDocumentation())
+                    }
+                }
             }
         }
 
@@ -109,11 +122,15 @@ open class DefaultPageCreator(
         header(1) { text(f.name) }
         +buildSignature(f)
         +contentForComments(f)
-        block("Parameters", 2, ContentKind.Parameters, f.children, f.platformData.toSet()) {
-            text(it.name ?: "<receiver>")
-            it.documentation.forEach { it.value.children.forEach { comment(it.root) } }
-        }
     }
 
     protected open fun TagWrapper.toHeaderString() = this.javaClass.toGenericString().split('.').last()
+
+    protected open fun Documentable.briefDocumentation() =
+        documentation.values
+            .firstOrNull()
+            ?.children
+            ?.firstOrNull()
+            ?.root
+            ?.docTagSummary() ?: ""
 }
\ No newline at end of file