mirror of
https://github.com/enso-org/enso.git
synced 2024-09-11 13:15:52 +03:00
Fix code docs, add new tags to doc parser, fix Tag.unrecognized
and parens in text. (#1452)
This commit is contained in:
parent
c4a0772190
commit
5e309bddcb
@ -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
|
||||
|
@ -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
|
||||
|
@ -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"
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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"`
|
||||
|
@ -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"`
|
||||
|
@ -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
|
||||
|
@ -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]
|
||||
}
|
||||
|
@ -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
|
||||
}
|
||||
|
@ -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"))
|
||||
)
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user