Merge pull request #11842 from lampepfl/scaladoc/doc-fix

Scaladoc: Fix brief comments in member documentation, remove artifact members

Author: romanowski

scaladoc/resources/dotty_res/styles/scalastyle.css

@@ -566,18 +566,22 @@ footer .pull-right {
   display: inline-block;
 }
 
+.documentableElement.expand .documentableBrief {
+  display: none;
+}
+
 .documentableAnchor {
   position: absolute;
   width: 24px;
   height: 24px;
   background: url('data:image/svg+xml;utf8,<svg width="24" height="24" viewBox="0 0 24 24" fill="darkgray" xmlns="http://www.w3.org/2000/svg"><path d="M21.2496 5.3C20.3496 4.5 19.2496 4 18.0496 4C16.8496 4 15.6496 4.5 14.8496 5.3L10.3496 9.8L11.7496 11.2L16.2496 6.7C17.2496 5.7 18.8496 5.7 19.8496 6.7C20.8496 7.7 20.8496 9.3 19.8496 10.3L15.3496 14.8L16.7496 16.2L21.2496 11.7C22.1496 10.8 22.5496 9.7 22.5496 8.5C22.5496 7.3 22.1496 6.2 21.2496 5.3Z"></path><path d="M8.35 16.7998C7.35 17.7998 5.75 17.7998 4.75 16.7998C3.75 15.7998 3.75 14.1998 4.75 13.1998L9.25 8.6998L7.85 7.2998L3.35 11.7998C1.55 13.5998 1.55 16.3998 3.35 18.1998C4.25 19.0998 5.35 19.4998 6.55 19.4998C7.75 19.4998 8.85 19.0998 9.75 18.1998L14.25 13.6998L12.85 12.2998L8.35 16.7998Z"></path></svg> ');
 }
 
-.documentableBrief {
+.memberDocumentation {
   font-size: 14px;
 }
 
-.documentableBrief>p{
+.memberDocumentation>p{
   margin: .5em 0 0 0;
 }
 

scaladoc/src/dotty/tools/scaladoc/renderers/MemberRenderer.scala

@@ -93,12 +93,13 @@ class MemberRenderer(signatureRenderer: SignatureRenderer)(using DocContext) ext
   }
 
   def memberInfo(m: Member): Seq[AppliedTag] =
+    val comment = m.docs
     val bodyContents = m.docs.fold(Nil)(e => renderDocPart(e.body) :: Nil)
 
     Seq(
-      div(cls := "documentableBrief doc")(bodyContents.take(1)),
+      div(cls := "documentableBrief doc")(comment.flatMap(_.short).fold("")(renderDocPart)),
       div(cls := "cover")(
-        div(cls := "doc")(bodyContents.drop(1)),
+        div(cls := "doc")(bodyContents),
         dl(cls := "attributes")(
           docAttributes(m),
           companion(m),
@@ -169,7 +170,7 @@ class MemberRenderer(signatureRenderer: SignatureRenderer)(using DocContext) ext
         span(cls := "modifiers"), // just to have padding on left
         div(
           div(cls := "originInfo")(originInfo(member):_*),
-          div(cls := "documentableBrief")(memberInfo(member)),
+          div(cls := "memberDocumentation")(memberInfo(member)),
         )
       )
     )

scaladoc/src/dotty/tools/scaladoc/tasty/ClassLikeSupport.scala

@@ -116,7 +116,7 @@ trait ClassLikeSupport:
           parseMethod(c, dd.symbol,specificKind = Kind.Extension(target, _))
         }
       // TODO check given methods?
-      case dd: DefDef if !dd.symbol.isHiddenByVisibility && dd.symbol.isGiven =>
+      case dd: DefDef if !dd.symbol.isHiddenByVisibility && dd.symbol.isGiven && !dd.symbol.isArtifact =>
         Some(dd.symbol.owner.memberType(dd.name))
           .filterNot(_.exists)
           .map { _ =>
@@ -125,7 +125,7 @@ trait ClassLikeSupport:
             )
           }
 
-      case dd: DefDef if !dd.symbol.isHiddenByVisibility && dd.symbol.isExported =>
+      case dd: DefDef if !dd.symbol.isHiddenByVisibility && dd.symbol.isExported && !dd.symbol.isArtifact =>
         val exportedTarget = dd.rhs.collect {
           case a: Apply => a.fun.asInstanceOf[Select]
           case s: Select => s
@@ -142,7 +142,7 @@ trait ClassLikeSupport:
         Some(parseMethod(c, dd.symbol, specificKind = Kind.Exported(_))
           .withOrigin(Origin.ExportedFrom(s"$instanceName.$functionName", dri)))
 
-      case dd: DefDef if !dd.symbol.isHiddenByVisibility && !dd.symbol.isGiven && !dd.symbol.isSyntheticFunc && !dd.symbol.isExtensionMethod =>
+      case dd: DefDef if !dd.symbol.isHiddenByVisibility && !dd.symbol.isGiven && !dd.symbol.isSyntheticFunc && !dd.symbol.isExtensionMethod && !dd.symbol.isArtifact =>
         Some(parseMethod(c, dd.symbol))
 
       case td: TypeDef if !td.symbol.flags.is(Flags.Synthetic) && (!td.symbol.flags.is(Flags.Case) || !td.symbol.flags.is(Flags.Enum)) =>

scaladoc/src/dotty/tools/scaladoc/tasty/SymOps.scala

@@ -109,6 +109,8 @@ class SymOps[Q <: Quotes](val q: Q) extends JavadocAnchorCreator with Scaladoc2A
 
     def isExtensionMethod: Boolean = sym.flags.is(Flags.ExtensionMethod)
 
+    def isArtifact: Boolean = sym.flags.is(Flags.Artifact)
+
     def isLeftAssoc(d: Symbol): Boolean = !d.name.endsWith(":")
 
     def extendedSymbol: Option[ValDef] =