diff options
author | Vlad Ureche <vlad.ureche@epfl.ch> | 2011-12-08 02:14:21 +0100 |
---|---|---|
committer | Vlad Ureche <vlad.ureche@epfl.ch> | 2011-12-08 02:14:21 +0100 |
commit | 4da259b26eb9d3409392fef91d36471cd7ac4354 (patch) | |
tree | 0fdbdc472631374c384be9f37d5848f125cddde1 | |
parent | 332fec96e31840878bed41dd7b5314b97d8da7c2 (diff) | |
download | scala-4da259b26eb9d3409392fef91d36471cd7ac4354.tar.gz scala-4da259b26eb9d3409392fef91d36471cd7ac4354.tar.bz2 scala-4da259b26eb9d3409392fef91d36471cd7ac4354.zip |
Fixed #5054, #5287
The documents with use cases should be restructured like:
/**
* The full definition, either used with an implicit value or with an explicit one.
*
* Some more explanation on implicits...
*
* @param lost a lost parameter
* @return some integer
*
* @usecase def test(): Int
*
* This takes the implicit value in scope.
*
* Example: `test()`
*
* @usecase def test(explicit: Int): Int
*
* This takes the explicit value passed.
*
* Example: `test(3)`
*/
def test(implicit lost: Int): Int
-rwxr-xr-x | src/compiler/scala/tools/nsc/ast/DocComments.scala | 2 | ||||
-rw-r--r-- | src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala | 20 | ||||
-rw-r--r-- | test/scaladoc/resources/SI_5054.scala | 10 | ||||
-rw-r--r-- | test/scaladoc/resources/SI_5054_q1.scala | 9 | ||||
-rw-r--r-- | test/scaladoc/resources/SI_5054_q2.scala | 9 | ||||
-rw-r--r-- | test/scaladoc/resources/SI_5054_q3.scala | 9 | ||||
-rw-r--r-- | test/scaladoc/resources/SI_5054_q4.scala | 9 | ||||
-rw-r--r-- | test/scaladoc/resources/SI_5054_q5.scala | 9 | ||||
-rw-r--r-- | test/scaladoc/resources/SI_5054_q6.scala | 9 | ||||
-rw-r--r-- | test/scaladoc/resources/SI_5054_q7.scala | 22 | ||||
-rw-r--r-- | test/scaladoc/scala/html/HtmlFactoryTest.scala | 101 |
11 files changed, 186 insertions, 23 deletions
diff --git a/src/compiler/scala/tools/nsc/ast/DocComments.scala b/src/compiler/scala/tools/nsc/ast/DocComments.scala index 9c598bca41..8d52a7bd2c 100755 --- a/src/compiler/scala/tools/nsc/ast/DocComments.scala +++ b/src/compiler/scala/tools/nsc/ast/DocComments.scala @@ -101,7 +101,7 @@ trait DocComments { self: Global => def getUseCases(dc: DocComment) = { for (uc <- dc.useCases; defn <- uc.expandedDefs(site)) yield (defn, - expandVariables(merge(cookedDocComment(sym), uc.comment.raw, defn, copyFirstPara = true), sym, site), + expandVariables(merge(cookedDocComment(sym), uc.comment.raw, defn), sym, site), uc.pos) } getDocComment(sym) map getUseCases getOrElse List() diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index a3b4dc4337..1fe96ed447 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -119,14 +119,18 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { else Public() } } - 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 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 deprecation = if (sym.isDeprecated) diff --git a/test/scaladoc/resources/SI_5054.scala b/test/scaladoc/resources/SI_5054.scala deleted file mode 100644 index 17167303e4..0000000000 --- a/test/scaladoc/resources/SI_5054.scala +++ /dev/null @@ -1,10 +0,0 @@ -class SI_5054 { - - /** - * A simple comment - * - * @param lost a lost parameter - * @usecase def test(): Int - */ - def test(implicit lost: Int): Int = lost -}
\ No newline at end of file diff --git a/test/scaladoc/resources/SI_5054_q1.scala b/test/scaladoc/resources/SI_5054_q1.scala new file mode 100644 index 0000000000..02d9be8dd0 --- /dev/null +++ b/test/scaladoc/resources/SI_5054_q1.scala @@ -0,0 +1,9 @@ +class SI_5054_q1 { + /** + * A simple comment + * + * @param lost a lost parameter + * @usecase def test(): Int + */ + def test(implicit lost: Int): Int = lost +} diff --git a/test/scaladoc/resources/SI_5054_q2.scala b/test/scaladoc/resources/SI_5054_q2.scala new file mode 100644 index 0000000000..c873731e5b --- /dev/null +++ b/test/scaladoc/resources/SI_5054_q2.scala @@ -0,0 +1,9 @@ +class SI_5054_q2 { + /** + * A simple comment + * + * @param lost a lost parameter + * @usecase def test(): Int + */ + final def test(implicit lost: Int): Int = lost +} diff --git a/test/scaladoc/resources/SI_5054_q3.scala b/test/scaladoc/resources/SI_5054_q3.scala new file mode 100644 index 0000000000..be5d22ffdc --- /dev/null +++ b/test/scaladoc/resources/SI_5054_q3.scala @@ -0,0 +1,9 @@ +class SI_5054_q3 { + /** + * A simple comment + * + * @param lost a lost parameter + * @usecase def test(): Int + */ + implicit def test(implicit lost: Int): Int = lost +} diff --git a/test/scaladoc/resources/SI_5054_q4.scala b/test/scaladoc/resources/SI_5054_q4.scala new file mode 100644 index 0000000000..4e5e4865f1 --- /dev/null +++ b/test/scaladoc/resources/SI_5054_q4.scala @@ -0,0 +1,9 @@ +abstract class SI_5054_q4 { + /** + * A simple comment + * + * @param lost a lost parameter + * @usecase def test(): Int + */ + def test(implicit lost: Int): Int +} diff --git a/test/scaladoc/resources/SI_5054_q5.scala b/test/scaladoc/resources/SI_5054_q5.scala new file mode 100644 index 0000000000..05ba7488eb --- /dev/null +++ b/test/scaladoc/resources/SI_5054_q5.scala @@ -0,0 +1,9 @@ +trait SI_5054_q5 { + /** + * A simple comment + * + * @param lost a lost parameter + * @usecase def test(): Int + */ + def test(implicit lost: Int): Int = lost +} diff --git a/test/scaladoc/resources/SI_5054_q6.scala b/test/scaladoc/resources/SI_5054_q6.scala new file mode 100644 index 0000000000..607be654a5 --- /dev/null +++ b/test/scaladoc/resources/SI_5054_q6.scala @@ -0,0 +1,9 @@ +trait SI_5054_q6 { + /** + * A simple comment + * + * @param lost a lost parameter + * @usecase def test(): Int + */ + def test(implicit lost: Int): Int +} diff --git a/test/scaladoc/resources/SI_5054_q7.scala b/test/scaladoc/resources/SI_5054_q7.scala new file mode 100644 index 0000000000..26d4b5fcf4 --- /dev/null +++ b/test/scaladoc/resources/SI_5054_q7.scala @@ -0,0 +1,22 @@ +trait SI_5054_q7 { + /** + * The full definition, either used with an implicit value or with an explicit one. + * + * Some more explanation on implicits... + * + * @param lost a lost parameter + * @return some integer + * @usecase def test(): Int + * + * This takes the implicit value in scope. + * + * Example: `test()` + * + * @usecase def test(explicit: Int): Int + * + * This takes the explicit value passed. + * + * Example: `test(3)` + */ + def test(implicit lost: Int): Int +} diff --git a/test/scaladoc/scala/html/HtmlFactoryTest.scala b/test/scaladoc/scala/html/HtmlFactoryTest.scala index c8dad4cf48..d1bfbb023f 100644 --- a/test/scaladoc/scala/html/HtmlFactoryTest.scala +++ b/test/scaladoc/scala/html/HtmlFactoryTest.scala @@ -378,15 +378,108 @@ object Test extends Properties("HtmlFactory") { true } - property("Use cases should override their original members - valid until signature is added to html") = { - createTemplate("SI_5054.scala") match { + // 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.contains("A simple comment") && - ! node.toString.contains("a lost parameter") + 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 + } + } + + 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 case individual signature test") = { + createTemplate("SI_5054_q7.scala") match { + case node: scala.xml.Node => + node.toString.replaceAll("\\s+","").contains(useCaseExplanation) + case _ => false + } + } { val files = createTemplates("basic.scala") |