Fix code docs, add new tags to doc parser, fix Tag.unrecognized and parens in text. (#1452)

distribution/std-lib/Base/src/Data/Time/Date.enso

@@ -11,7 +11,7 @@ polyglot java import org.enso.base.Time_Utils
 
 type Date
 
-    ## `Date` represents a date, often viewed as year-month-day. For example,
+    ## This type represents a date, often viewed as year-month-day. For example,
        the value "2nd October 2007" can be stored in a `Date`.
 
        This class does not store or represent a time or timezone. Instead, it

distribution/std-lib/Base/src/Data/Time/Duration.enso

@@ -23,6 +23,7 @@ type Duration
     + other = Duration (this.internal_period . plus other.internal_period . normalized) (this.internal_duration . plus other.internal_duration)
 
     ## Subtract specified amount of time from this duration.
+
        > Example
          Subtract 11 months from a duration of 3 years
              3.years - 11.months

distribution/std-lib/Base/src/Data/Time/Locale.enso

@@ -94,6 +94,7 @@ us = here.from_language_tag "en-US"
 
    In addition to the basic constructors, it can take a vector containing locale
    properties.
+
    > Example
      A locale representing en-GB.UTF-8.
          Locale.new "en" "GB" "UTF-8"

distribution/std-lib/Base/src/Data/Time/Time_Of_Day.enso

@@ -12,7 +12,7 @@ polyglot java import org.enso.base.Time_Utils
 
 type Time_Of_Day
 
-    ## `Time_Of_Day` is a date-time object that represents a time, often viewed
+    ## This type is a date-time object that represents a time, often viewed
        as hour-minute-second. Time is represented to nanosecond precision. For
        example, the value "13:45.30.123456789" can be stored in a `Time_Of_Day`.
     type Time_Of_Day internal_local_time

distribution/std-lib/Base/src/Data/Vector.enso

@@ -331,6 +331,7 @@ type Vector
        elements of `this` and `that`.
        The result of this function is a vector of length being the shorter of
        `this` and `that`, containing results of calling `function`.
+
        > Example
          To pairwise-sum two vectors:
              zip [1, 2, 3] [4, 5, 6] (+) == [5, 7, 9]
@@ -362,6 +363,7 @@ type Vector
        > Example
          The following code returns [2, 3, 4].
              [1, 2, 3, 4].tail
+
        > Example
          Empty vectors return `Nothing`.
              [].tail == Nothing
@@ -373,6 +375,7 @@ type Vector
        > Example
          The following code returns [1, 2, 3].
              [1, 2, 3, 4].init
+
        > Example
          Empty vectors return `Nothing`.
              [].init == Nothing
@@ -384,6 +387,7 @@ type Vector
        > Example
          The following code returns 4.
              [1, 2, 3, 4].last
+
        > Example
          Empty vectors return `Nothing`.
              [].last == Nothing
@@ -395,6 +399,7 @@ type Vector
        > Example
          The following code returns 1.
              [1, 2, 3, 4].first
+
        > Example
          Empty vectors return `Nothing`.
              [].first == Nothing
@@ -406,6 +411,7 @@ type Vector
        > Example
          The following code returns [2, 3, 4].
              [1, 2, 3, 4].rest
+
        > Example
          Empty vectors return `Nothing`.
              [].rest == Nothing

distribution/std-lib/Table/src/Data/Column.enso

@@ -224,6 +224,7 @@ type Column
     ## Selects only the rows of this column that correspond to `True` values in
        `indexes`.
        This is useful for filtering the rows by given predicate.
+
        > Example
          Select only the rows of `my_column` where the `status_column` column
          has the value `"Valid"`

distribution/std-lib/Table/src/Data/Table.enso

@@ -56,6 +56,7 @@ type Table
     ## Selects only the rows of this table that correspond to `True` values in
        `indexes`.
        This is useful for filtering the rows by given predicate.
+
        > Example
          Select only the rows of `my_table` where the `"Status"` column has the
          value `"Valid"`

docs/syntax/comments.md

@@ -102,19 +102,19 @@ The documentation syntax is broken down into the following elements.
 Tags allow users to annotate their construct with information about its usage
 state. The documentation syntax supports the following tags:
 
+- `ADDED`: Used to describe when a given construct was added to the library.
+- `ADVANCED`: Items that are _not_ private, but are for power users.
 - `DEPRECATED`: Used for constructs that should no longer be used and that may
   be removed in the future.
 - `MODIFIED`: Used for constructs that have had their behaviour change after a
   certain version of the library.
-- `ADDED`: Used to describe when a given construct was added to the library.
-- `UPCOMING`: Used to describe constructs that will be added in future versions
-  of the library.
+- `PRIVATE`: Used to describe constructs that are private in the language.
 - `REMOVED`: Used to describe constructs that have been removed and are no
   longer functional.
-- `PRIVATE`: Used to describe constructs that are private in the language.
-- `ADVANCED`: Items that are _not_ private, but are for power users.
 - `TEXT_ONLY`: Items that do not apply to the graphical mode.
 - `UNSTABLE`: Used for items that are not yet considered stable.
+- `UPCOMING`: Used to describe constructs that will be added in future versions
+  of the library.
 
 Tags are added at the _top_ of the documentation block, and may also be
 accompanied by a description. This description directly follows the tag

lib/scala/syntax/definition/src/main/scala/org/enso/syntax/text/ast/Doc.scala

@@ -193,9 +193,10 @@ object Doc {
     }
     object CodeBlock {
       def apply(elem: CodeBlock.Line): CodeBlock = CodeBlock(List1(elem))
-      def apply(elems: CodeBlock.Line*): CodeBlock = CodeBlock(
-        List1(elems.head, elems.tail.toList)
-      )
+      def apply(elems: CodeBlock.Line*): CodeBlock =
+        CodeBlock(
+          List1(elems.head, elems.tail.toList)
+        )
 
       /** Inline - line of code which is in line with other elements
         * Line - elem which is a part of Code Block
@@ -510,8 +511,7 @@ object Doc {
     /** Tag - one single tag for Tags
       *
       * @param indent - indent of tag
-      * @param typ - type of tag, which can be
-      * Deprecated, Added, Removed, Modified, Upcoming or Unrecognized
+      * @param typ - type of tag, which can be one of listed in object `Type`
       * @param details - optional information for tag
       */
     final case class Tag(indent: Int, typ: Tag.Type, details: Option[String])
@@ -538,10 +538,14 @@ object Doc {
 
       sealed trait Type
       object Type {
-        case object Deprecated extends Type
         case object Added      extends Type
-        case object Removed    extends Type
+        case object Advanced   extends Type
+        case object Deprecated extends Type
         case object Modified   extends Type
+        case object Private    extends Type
+        case object Removed    extends Type
+        case object TextOnly   extends Type
+        case object Unstable   extends Type
         case object Upcoming   extends Type
         val codes = ADT.constructors[Type]
       }

lib/scala/syntax/definition/src/main/scala/org/enso/syntax/text/spec/DocParserDef.scala

@@ -61,7 +61,7 @@ case class DocParserDef() extends Parser[Doc] {
 
   val char: Pattern = lowerChar | upperChar
   val specialChars: Pattern =
-    "," | "." | ":" | ";" | "/" | "\\" | "’" | "=" | "'" | "|" | "+" | "-" | "#" | "\""
+    "," | "." | ":" | ";" | "/" | "\\" | "’" | "=" | "'" | "|" | "+" | "-" | "#" | "\"" | "(" | ")"
   val possibleChars: Pattern = char | digit | whitespace | specialChars
 
   val normalText: Pattern = possibleChars.many1
@@ -153,7 +153,9 @@ case class DocParserDef() extends Parser[Doc] {
                 pushTag(section.currentIndentRaw, tagType, tagDet)
               }
             }
-            if (!containsTag && !elem.contains(newline)) {
+            if (
+              !containsTag && !elem.contains(newline) && inArray.tail.isEmpty
+            ) {
               pushTag(section.currentIndentRaw, Tags.Tag.Unrecognized, in)
               containsTag = true
             }

lib/scala/syntax/specialization/shared/src/test/scala/org/enso/syntax/text/DocParserTests.scala

@@ -643,9 +643,15 @@ class DocParserTests extends AnyFlatSpec with Matchers {
     ),
     Synopsis(Section.Raw("Foo"))
   )
-  """   ALAMAKOTA a kot ma ale
+  """   ALAMAKOTA
+    | DEPRECATED
+    | PRIVATE
     | foo bar""".stripMargin.replaceAll(System.lineSeparator(), "\n") ?= Doc(
-    Tags(Tags.Tag(3, Tags.Tag.Unrecognized, "ALAMAKOTA a kot ma ale")),
+    Tags(
+      Tags.Tag(3, Tags.Tag.Unrecognized, "ALAMAKOTA"),
+      Tags.Tag(1, Tags.Tag.Type.Deprecated),
+      Tags.Tag(1, Tags.Tag.Type.Private)
+    ),
     Synopsis(Section.Raw(1, "foo bar"))
   )