Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Fixed "Definition Classes" in bug #5287 #63

Closed
wants to merge 3 commits into from

1 participant

Vlad Ureche
Vlad Ureche
Collaborator

and fixed usecase param, tparam and return overriding.

Vlad Ureche VladUreche closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Dec 16, 2011
  1. Vlad Ureche
Commits on Dec 19, 2011
  1. Vlad Ureche
  2. Vlad Ureche

    Fixed usecase @param/@tparam/@return overriding

    VladUreche authored
    which was not working at all previously
This page is out of date. Refresh to see the latest.
10 src/compiler/scala/tools/nsc/ast/DocComments.scala
View
@@ -99,7 +99,7 @@ trait DocComments { self: Global =>
*/
def useCases(sym: Symbol, site: Symbol): List[(Symbol, String, Position)] = {
def getUseCases(dc: DocComment) = {
- for (uc <- dc.useCases; defn <- uc.expandedDefs(site)) yield
+ for (uc <- dc.useCases; defn <- uc.expandedDefs(sym, site)) yield
(defn,
expandVariables(merge(cookedDocComment(sym), uc.comment.raw, defn), sym, site),
uc.pos)
@@ -346,7 +346,7 @@ trait DocComments { self: Global =>
var defined: List[Symbol] = List() // initialized by Typer
var aliases: List[Symbol] = List() // initialized by Typer
- def expandedDefs(site: Symbol): List[Symbol] = {
+ def expandedDefs(sym: Symbol, site: Symbol): List[Symbol] = {
def select(site: Type, name: Name, orElse: => Type): Type = {
val member = site.nonPrivateMember(name)
@@ -424,8 +424,10 @@ trait DocComments { self: Global =>
}
for (defn <- defined) yield {
- defn.cloneSymbol.setFlag(Flags.SYNTHETIC).setInfo(
- substAliases(defn.info).asSeenFrom(site.thisType, defn.owner))
+ val useCase = defn.cloneSymbol
+ useCase.owner = sym.owner
+ useCase.flags = sym.flags
+ useCase.setFlag(Flags.SYNTHETIC).setInfo(substAliases(defn.info).asSeenFrom(site.thisType, sym.owner))
}
}
}
34 src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
View
@@ -100,11 +100,15 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
if (inTpl == null) None else thisFactory.comment(sym, inTpl)
override def inTemplate = inTpl
override def toRoot: List[MemberImpl] = this :: inTpl.toRoot
- def inDefinitionTemplates =
- if (inTpl == null)
- makeRootPackage.toList
- else
- makeTemplate(sym.owner) :: (sym.allOverriddenSymbols map { inhSym => makeTemplate(inhSym.owner) })
+ def inDefinitionTemplates = this match {
+ case mb: NonTemplateMemberEntity if (mb.useCaseOf.isDefined) =>
+ mb.useCaseOf.get.inDefinitionTemplates
+ case _ =>
+ if (inTpl == null)
+ makeRootPackage.toList
+ else
+ makeTemplate(sym.owner) :: (sym.allOverriddenSymbols map { inhSym => makeTemplate(inhSym.owner) })
+ }
def visibility = {
if (sym.isPrivateLocal) PrivateInInstance()
else if (sym.isProtectedLocal) ProtectedInInstance()
@@ -119,18 +123,14 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
else Public()
}
}
- def flags = this match {
- // workaround for uninitialized flags in use cases - see SI-5054
- case m: NonTemplateMemberEntity if (m.useCaseOf.isDefined) =>
- m.useCaseOf.get.flags
- case _ =>
- val fgs = mutable.ListBuffer.empty[Paragraph]
- if (sym.isImplicit) fgs += Paragraph(Text("implicit"))
- if (sym.isSealed) fgs += Paragraph(Text("sealed"))
- if (!sym.isTrait && (sym hasFlag Flags.ABSTRACT)) fgs += Paragraph(Text("abstract"))
- if (!sym.isTrait && (sym hasFlag Flags.DEFERRED)) fgs += Paragraph(Text("abstract"))
- if (!sym.isModule && (sym hasFlag Flags.FINAL)) fgs += Paragraph(Text("final"))
- fgs.toList
+ def flags = {
+ val fgs = mutable.ListBuffer.empty[Paragraph]
+ if (sym.isImplicit) fgs += Paragraph(Text("implicit"))
+ if (sym.isSealed) fgs += Paragraph(Text("sealed"))
+ if (!sym.isTrait && (sym hasFlag Flags.ABSTRACT)) fgs += Paragraph(Text("abstract"))
+ if (!sym.isTrait && (sym hasFlag Flags.DEFERRED)) fgs += Paragraph(Text("abstract"))
+ if (!sym.isModule && (sym hasFlag Flags.FINAL)) fgs += Paragraph(Text("final"))
+ fgs.toList
}
def deprecation =
if (sym.isDeprecated)
26 src/compiler/scala/tools/nsc/util/DocStrings.scala
View
@@ -71,13 +71,35 @@ object DocStrings {
* Every section starts with a `@` and extends to the next `@`, or
* to the end of the comment string, but excluding the final two
* characters which terminate the comment.
+ *
+ * Also take usecases into account - they need to expand until the next
+ * @usecase or the end of the string, as they might include other sections
+ * of their own
*/
def tagIndex(str: String, p: Int => Boolean = (idx => true)): List[(Int, Int)] =
findAll(str, 0) (idx => str(idx) == '@' && p(idx)) match {
case List() => List()
- case idxs => idxs zip (idxs.tail ::: List(str.length - 2))
+ case idxs => {
+ val idxs2 = mergeUsecaseSections(str, idxs)
+ idxs2 zip (idxs2.tail ::: List(str.length - 2))
+ }
}
-
+
+ /**
+ * Merge sections following an @usecase into the usecase comment, so they
+ * can override the parent symbol's sections
+ */
+ def mergeUsecaseSections(str: String, idxs: List[Int]): List[Int] = {
+ idxs.find(str.substring(_).startsWith("@usecase")) match {
+ case Some(firstUC) =>
+ val commentSections = idxs.take(idxs.indexOf(firstUC))
+ val usecaseSections = idxs.drop(idxs.indexOf(firstUC)).filter(str.substring(_).startsWith("@usecase"))
+ commentSections ::: usecaseSections
+ case None =>
+ idxs
+ }
+ }
+
/** Does interval `iv` start with given `tag`?
*/
def startsWithTag(str: String, section: (Int, Int), tag: String): Boolean =
3  src/partest/scala/tools/partest/nest/CompileManager.scala
View
@@ -75,7 +75,8 @@ class DirectCompiler(val fileManager: FileManager) extends SimpleCompiler {
val logWriter = new FileWriter(log)
// check whether there is a ".flags" file
- val flagsFileName = "%s.flags" format (basename(log.getName) dropRight 4) // 4 is "-run" or similar
+ val logFile = basename(log.getName)
+ val flagsFileName = "%s.flags" format (logFile.substring(0, logFile.lastIndexOf("-")))
val argString = (io.File(log).parent / flagsFileName) ifFile (x => updatePluginPath(x.slurp())) getOrElse ""
val allOpts = fileManager.SCALAC_OPTS.toList ::: argString.split(' ').toList.filter(_.length > 0)
val args = allOpts.toList
8 test/scaladoc/resources/SI_5054_q7.scala
View
@@ -6,17 +6,17 @@ trait SI_5054_q7 {
*
* @param lost a lost parameter
* @return some integer
- * @usecase def test(): Int
+ * @usecase def test1(): Int
*
* This takes the implicit value in scope.
*
- * Example: `test()`
+ * Example: `test1()`
*
- * @usecase def test(explicit: Int): Int
+ * @usecase def test2(explicit: Int): Int
*
* This takes the explicit value passed.
*
- * Example: `test(3)`
+ * Example: `test2(3)`
*/
def test(implicit lost: Int): Int
}
17 test/scaladoc/resources/SI_5287.scala
View
@@ -0,0 +1,17 @@
+trait SI_5287_A {
+ def method(implicit a: Int): Int = a
+}
+
+trait SI_5287_B extends SI_5287_A {
+ override def method(implicit a: Int): Int = a + 1
+}
+
+trait SI_5287 extends SI_5287_B{
+ /**
+ * Some explanation
+ *
+ * @usecase def method(): Int
+ * The usecase explanation
+ */
+ override def method(implicit a: Int): Int = a + 3
+}
1  test/scaladoc/scala/html.flags
View
@@ -0,0 +1 @@
+-encoding UTF-8
1  test/scaladoc/scala/html/HtmlFactoryTest.flags
View
@@ -0,0 +1 @@
+-encoding UTF-8
305 test/scaladoc/scala/html/HtmlFactoryTest.scala
View
@@ -21,6 +21,9 @@ object XMLUtil {
}
object Test extends Properties("HtmlFactory") {
+
+ final val RESOURCES = "test/scaladoc/resources/"
+
import scala.tools.nsc.doc.{DocFactory, Settings}
import scala.tools.nsc.doc.model.IndexModelFactory
import scala.tools.nsc.doc.html.HtmlFactory
@@ -47,7 +50,7 @@ object Test extends Properties("HtmlFactory") {
def createTemplates(basename: String) = {
val result = scala.collection.mutable.Map[String, scala.xml.NodeSeq]()
- createFactory.makeUniverse(List("test/scaladoc/resources/"+basename)) match {
+ createFactory.makeUniverse(List(RESOURCES+basename)) match {
case Some(universe) => {
val index = IndexModelFactory.makeIndex(universe)
(new HtmlFactory(universe, index)).writeTemplates((page) => {
@@ -61,7 +64,7 @@ object Test extends Properties("HtmlFactory") {
}
def createReferenceIndex(basename: String) = {
- createFactory.makeUniverse(List("test/scaladoc/resources/"+basename)) match {
+ createFactory.makeUniverse(List(RESOURCES+basename)) match {
case Some(universe) => {
val index = IndexModelFactory.makeIndex(universe)
val pages = index.firstLetterIndex.map({
@@ -81,6 +84,58 @@ object Test extends Properties("HtmlFactory") {
val html = scala.stripSuffix(".scala") + ".html"
createTemplates(scala)(html)
}
+
+ /**
+ * This tests the text without the markup - ex:
+ *
+ * <h4 class="signature">
+ * <span class="modifier_kind">
+ * <span class="modifier">implicit</span>
+ * <span class="kind">def</span>
+ * </span>
+ * <span class="symbol">
+ * <span class="name">test</span><span class="params">()</span><span class="result">: <span name="scala.Int" class="extype">Int</span></span>
+ * </span>
+ * </h4>
+ *
+ * becomes:
+ *
+ * implicit def test(): Int
+ *
+ * and is required to contain the text in the given checks
+ *
+ * NOTE: Comparison is done ignoring all whitespace
+ */
+ def checkText(scalaFile: String, debug: Boolean = true)(checks: (Option[String], String, Boolean)*): Boolean = {
+ val htmlFile = scalaFile.stripSuffix(".scala") + ".html"
+ val htmlAllFiles = createTemplates(scalaFile)
+ var result = true
+
+ for ((fileHint, check, expected) <- checks) {
+ // resolve the file to be checked
+ val fileName = fileHint match {
+ case Some(file) =>
+ if (file endsWith ".html")
+ file
+ else
+ file + ".html"
+ case None =>
+ htmlFile
+ }
+ val fileText = htmlAllFiles(fileName).text.replace('→',' ').replaceAll("\\s+","")
+ val checkText = check.replace('→',' ').replaceAll("\\s+","")
+ val checkValue = fileText.contains(checkText) == expected
+ if (debug && (!checkValue)) {
+ Console.err.println("Check failed: ")
+ Console.err.println("HTML: " + fileText)
+ Console.err.println("Check: " + checkText)
+ }
+ result &&= checkValue
+ }
+
+ result
+ }
+
def shortComments(root: scala.xml.Node) =
XMLUtil.stripGroup(root).descendant.flatMap {
@@ -377,113 +432,159 @@ object Test extends Properties("HtmlFactory") {
createTemplate("SI_4898.scala")
true
}
-
- // A piece of the signature - corresponding to the use case
- def signature(no: Int, modifier: String) = ("""
- <li visbl="pub" name="SI_5054_q""" + no + """#test" data-isabs="false">
- <a id="test():Int"></a>
- <h4 class="signature">
- <span class="modifier_kind">
- <span class="modifier">""" + modifier + """</span>
- <span class="kind">def</span>
- </span>
- <span class="symbol">
- <span class="name">test</span><span class="params">()</span><span class="result">: <span name="scala.Int" class="extype">Int</span></span>
- </span>
- </h4>
- <p class="shortcomment cmt">[use case]
- </p>
- </li>""").replaceAll("\\s+", "")
-
- property("Use cases should override their original members") = {
- createTemplate("SI_5054_q1.scala") match {
- case node: scala.xml.Node =>
- node.toString.replaceAll("\\s+","").contains(signature(1, ""))
- case _ => false
- }
- }
-
- property("Use cases should keep their flags - final should not be lost") = {
- createTemplate("SI_5054_q2.scala") match {
- case node: scala.xml.Node =>
- node.toString.replaceAll("\\s+","").contains(signature(2, "final"))
- case _ => false
- }
- }
- property("Use cases should keep their flags - implicit should not be lost") = {
- createTemplate("SI_5054_q3.scala") match {
- case node: scala.xml.Node =>
- node.toString.replaceAll("\\s+","").contains(signature(3, "implicit"))
- case _ => false
- }
- }
-
- property("Use cases should keep their flags - real abstract should not be lost") = {
- createTemplate("SI_5054_q4.scala") match {
- case node: scala.xml.Node =>
- node.toString.replaceAll("\\s+","").contains(signature(4, "abstract"))
- case _ => false
- }
- }
-
- property("Use cases should keep their flags - traits should not be affected") = {
- createTemplate("SI_5054_q5.scala") match {
- case node: scala.xml.Node =>
- node.toString.replaceAll("\\s+","").contains(signature(5, ""))
- case _ => false
- }
- }
-
- property("Use cases should keep their flags - traits should not be affected") = {
- createTemplate("SI_5054_q6.scala") match {
- case node: scala.xml.Node =>
- node.toString.replaceAll("\\s+","").contains(signature(6, "abstract"))
- case _ => false
- }
- }
+ property("Use cases should override their original members") =
+ checkText("SI_5054_q1.scala")(
+ (None,"""def test(): Int""", true),
+ (None,"""def test(implicit lost: Int): Int""", false)
+ )
+
+ property("Use cases should keep their flags - final should not be lost") =
+ checkText("SI_5054_q2.scala")((None, """final def test(): Int""", true))
- val useCaseExplanation = """
- </li><li visbl="pub" name="SI_5054_q7#test" data-isabs="false">
- <a id="test():Int"></a>
- <h4 class="signature">
- <span class="modifier_kind">
- <span class="modifier">abstract </span>
- <span class="kind">def</span>
- </span>
- <span class="symbol">
- <span class="name">test</span><span class="params">()</span><span class="result">: <span name="scala.Int" class="extype">Int</span></span>
- </span>
- </h4>
- <p class="shortcomment cmt">[use case] This takes the implicit value in scope.</p><div class="fullcomment">[use case] <div class="comment cmt"><p>This takes the implicit value in scope.</p><p>Example: <code>test()</code></p></div><dl class="paramcmts block"><dt>returns</dt><dd class="cmt"><p>some integer
- </p></dd></dl></div>
- </li><li visbl="pub" name="SI_5054_q7#test" data-isabs="false">
- <a id="test(Int):Int"></a>
- <h4 class="signature">
- <span class="modifier_kind">
- <span class="modifier">abstract </span>
- <span class="kind">def</span>
- </span>
- <span class="symbol">
- <span class="name">test</span><span class="params">(<span name="explicit">explicit: <span name="scala.Int" class="extype">Int</span></span>)</span><span class="result">: <span name="scala.Int" class="extype">Int</span></span>
- </span>
- </h4>
- <p class="shortcomment cmt">[use case] This takes the explicit value passed.</p><div class="fullcomment">[use case] <div class="comment cmt"><p>This takes the explicit value passed.</p><p>Example: <code>test(3)</code></p></div><dl class="paramcmts block"><dt>returns</dt><dd class="cmt"><p>some integer
- </p></dd></dl></div>
- </li>
- """.replaceAll("\\s+","")
+ property("Use cases should keep their flags - implicit should not be lost") =
+ checkText("SI_5054_q3.scala")((None, """implicit def test(): Int""", true))
- property("Use case individual signature test") = {
- createTemplate("SI_5054_q7.scala") match {
- case node: scala.xml.Node =>
- node.toString.replaceAll("\\s+","").contains(useCaseExplanation)
- case _ => false
- }
+ property("Use cases should keep their flags - real abstract should not be lost") =
+ checkText("SI_5054_q4.scala")((None, """abstract def test(): Int""", true))
+
+ property("Use cases should keep their flags - traits should not be affected") =
+ checkText("SI_5054_q5.scala")((None, """def test(): Int""", true))
+
+ property("Use cases should keep their flags - traits should not be affected") =
+ checkText("SI_5054_q6.scala")((None, """abstract def test(): Int""", true))
+
+ property("Use case individual signature test") =
+ checkText("SI_5054_q7.scala")(
+ (None, """abstract def test2(explicit: Int): Int [use case] This takes the explicit value passed.""", true),
+ (None, """abstract def test1(): Int [use case] This takes the implicit value in scope.""", true)
+ )
+
+ property("Display correct \"Definition classes\"") =
+ checkText("SI_5287.scala")(
+ (None,
+ """def method(): Int
+ [use case] The usecase explanation
+ [use case] The usecase explanation
+ Definition Classes SI_5287 SI_5287_B SI_5287_A""", true)
+ ) // the explanation appears twice, as small comment and full comment
+
+
+ property("Correct comment inheritance for overriding") =
+ checkText("implicit-inheritance-override.scala")(
+ (Some("Base"),
+ """def function[T](arg1: T, arg2: String): Double
+ The base comment.
+ The base comment. And another sentence...
+ T the type of the first argument
+ arg1 The T term comment
+ arg2 The string comment
+ returns The return comment
+ """, true),
+ (Some("DerivedA"),
+ """def function[T](arg1: T, arg2: String): Double
+ Overriding the comment, the params and returns comments should stay the same.
+ Overriding the comment, the params and returns comments should stay the same.
+ T the type of the first argument
+ arg1 The T term comment
+ arg2 The string comment
+ returns The return comment
+ """, true),
+ (Some("DerivedB"),
+ """def function[T](arg1: T, arg2: String): Double
+ T the type of the first argument
+ arg1 The overridden T term comment
+ arg2 The overridden string comment
+ returns The return comment
+ """, true),
+ (Some("DerivedC"),
+ """def function[T](arg1: T, arg2: String): Double
+ T the type of the first argument
+ arg1 The T term comment
+ arg2 The string comment
+ returns The overridden return comment
+ """, true),
+ (Some("DerivedD"),
+ """def function[T](arg1: T, arg2: String): Double
+ T The overriden type parameter comment
+ arg1 The T term comment
+ arg2 The string comment
+ returns The return comment
+ """, true)
+ )
+
+ for (useCaseFile <- List("UseCaseInheritance", "UseCaseOverrideInheritance")) {
+ property("Correct comment inheritance for usecases") =
+ checkText("implicit-inheritance-usecase.scala")(
+ (Some(useCaseFile),
+ """def missing_arg[T](arg1: T): Double
+ [use case]
+ [use case]
+ T The type parameter
+ arg1 The T term comment
+ returns The return comment
+ """, true),
+ (Some(useCaseFile),
+ """def missing_targ(arg1: Int, arg2: String): Double
+ [use case]
+ [use case]
+ arg1 The T term comment
+ arg2 The string comment
+ returns The return comment
+ """, true),
+ (Some(useCaseFile),
+ """def overridden_arg1[T](implicit arg1: T, arg2: String): Double
+ [use case]
+ [use case]
+ T The type parameter
+ arg1 The overridden T term comment
+ arg2 The string comment
+ returns The return comment
+ """, true),
+ (Some(useCaseFile),
+ """def overridden_targ[T](implicit arg1: T, arg2: String): Double
+ [use case]
+ [use case]
+ T The overridden type parameter comment
+ arg1 The T term comment
+ arg2 The string comment
+ returns The return comment
+ """, true),
+ (Some(useCaseFile),
+ """def overridden_return[T](implicit arg1: T, arg2: String): Double
+ [use case]
+ [use case]
+ T The type parameter
+ arg1 The T term comment
+ arg2 The string comment
+ returns The overridden return comment
+ """, true),
+ (Some(useCaseFile),
+ """def added_arg[T](implicit arg1: T, arg2: String, arg3: Float): Double
+ [use case]
+ [use case]
+ T The type parameter
+ arg1 The T term comment
+ arg2 The string comment
+ arg3 The added float comment
+ returns The return comment
+ """, true),
+ (Some(useCaseFile),
+ """def overridden_comment[T](implicit arg1: T, arg2: String): Double
+ [use case] The overridden comment.
+ [use case] The overridden comment.
+ T The type parameter
+ arg1 The T term comment
+ arg2 The string comment
+ returns The return comment
+ """, true)
+ )
}
+
{
val files = createTemplates("basic.scala")
- println(files)
+ //println(files)
property("class") = files.get("com/example/p1/Clazz.html") match {
case Some(node: scala.xml.Node) => {
Something went wrong with that request. Please try again.