Fix Invalid Comment Edge Case

According to [the XML specification](https://www.w3.org/TR/xml11//#IDA5CES "W3 XML") XML comments can not end in `--->`. Prior to this commit creating a comment of the form `Comment("invalid-")` would yield no error though it should, since it is rendered as `<!--invalid--->`. This commit makes such `String` values yield an `IllegalArgumentException`.

A companion object was also added with two helper methods, `validated` and `validatedOpt`, which allow for a user of the library to check if a `String` is valid without having to `catch` the `IllegalArgumentException`.

Author: isomarcte

shared/src/main/scala/scala/xml/Comment.scala

@@ -14,6 +14,8 @@ package xml
  *
  * @author Burak Emir
  * @param commentText the text contained in this node, may not contain "--"
+ *        and the final character may not be `-` to prevent a closing span of `-->`
+ *        which is invalid. [[https://www.w3.org/TR/xml11//#IDA5CES]]
  */
 case class Comment(commentText: String) extends SpecialNode {
 
@@ -22,8 +24,12 @@ case class Comment(commentText: String) extends SpecialNode {
   final override def doCollectNamespaces = false
   final override def doTransform = false
 
-  if (commentText contains "--")
+  if (commentText.contains("--")) {
     throw new IllegalArgumentException("text contains \"--\"")
+  }
+  if (commentText.length > 0 && commentText.charAt(commentText.length - 1) == '-') {
+    throw new IllegalArgumentException("The final character of a XML comment may not be '-'. See https://www.w3.org/TR/xml11//#IDA5CES")
+  }
 
   /**
    * Appends &quot;<!-- text -->&quot; to this string buffer.

shared/src/test/scala/scala/xml/CommentTest.scala

@@ -0,0 +1,30 @@
+package scala.xml
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+final class CommentTest {
+
+  @Test(expected=classOf[IllegalArgumentException])
+  def invalidCommentWithTwoDashes: Unit = {
+    Comment("invalid--comment")
+  }
+
+  @Test(expected=classOf[IllegalArgumentException])
+  def invalidCommentWithFinalDash: Unit = {
+    Comment("invalid comment-")
+  }
+
+  @Test
+  def validCommentWithDash: Unit = {
+    val valid: String = "valid-comment"
+    assertEquals(s"<!--${valid}-->", Comment(valid).toString)
+  }
+
+  @Test
+  def validEmptyComment: Unit = {
+    val valid: String = ""
+    assertEquals(s"<!--${valid}-->", Comment(valid).toString)
+  }
+}