Initial commit

pkl-doc/src/test/files/DocGeneratorTest/input/com.externalpackage/doc-package-info.pkl

@@ -0,0 +1,22 @@
+amends "pkl:DocPackageInfo"
+
+name = "com.externalpackage"
+version = "1.2.3"
+importUri = "https://pkl.io/"
+authors {
+  "publisher-externalpackage@group.apple.com"
+}
+sourceCode = "https://example.com/externalpackage/"
+sourceCodeUrlScheme = "https://example.com/blob/\(version)%{path}#L%{line}-L%{endLine}"
+issueTracker = "https://example.com/externalpackage/issues"
+
+dependencies {
+  new {
+    name = "pkl"
+    // use fixed version to avoid churn in expected test outputs
+    version = "0.24.0"
+    sourceCode = "https://github.com/apple/\(name)/blob/dev/stdlib/"
+    sourceCodeUrlScheme = "https://github.com/apple/\(name)/blob/\(version)/stdlib%{path}#L%{line}-L%{endLine}"
+    documentation = "https://pkl-lang.org/stdlib/\(name)/\(version)/"
+  }
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.externalpackage/external1.pkl

@@ -0,0 +1,3 @@
+module com.externalpackage.external1
+
+class MyClass

pkl-doc/src/test/files/DocGeneratorTest/input/com.externalpackage/external2.pkl

@@ -0,0 +1,3 @@
+module com.externalpackage.external2
+
+class MyClass

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/baseModule.pkl

@@ -0,0 +1,7 @@
+open module com.package1.baseModule
+
+baseProperty = 42
+
+function baseMethod() = 42
+
+class BaseClass {}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/classAnnotations.pkl

@@ -0,0 +1,30 @@
+open module com.package1.classAnnotations
+
+/// This [AnnotatedClss] thought to have a correctly spelled name.
+@Deprecated {
+  message = "Spelling mistake."
+  replaceWith = "AnnotatedClass"
+}
+@AlsoKnownAs {
+  names { "OtherName" }
+}
+class AnnotatedClss
+
+/// This [AnnotatedClssWithExpandableComment] thought to have a correctly spelled name.
+///
+/// Unfortunately, it did not, as we explain in this expandable comment.
+@Deprecated {
+  message = "Spelling mistake."
+  replaceWith = "AnnotatedClass"
+}
+@AlsoKnownAs {
+  names { "OtherName" }
+}
+class AnnotatedClssWithExpandableComment
+
+// This [AnnotatedClass] indeed has a properly spelled name, but no doc comment.
+@AlsoKnownAs {
+  names { "OtherName" }
+}
+@Deprecated // omit optional arguments
+class AnnotatedClass

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/classComments.pkl

@@ -0,0 +1,145 @@
+/// The greatest breakthrough since ever.
+///
+/// ### Installation
+///
+/// Just follow these simple steps:
+///
+/// 1. Install it
+///     1. I promise it's easy.
+///     2. You'll figure it out.
+/// 1. Install it
+///     ```
+///     name = "Pigeon"
+///     age = 42
+///     ```
+/// 1. Install it
+///
+/// Let me **emphasize** how *simple* this is.
+///
+/// 😀😀😀 emoji day 😎😎😎 don't get 😡😡😡
+///
+/// ### Code
+///
+/// The code is beautiful:
+///
+/// ```
+/// /// example module
+/// module foo.bar
+///
+/// person {
+///   name = "Pigeon"
+///   age = 42
+/// }
+///
+/// function sing() = "tra-la-la"
+///
+/// class Person {
+///   name: String
+///   age: Int
+/// }
+/// ```
+///
+/// ### Random Tips
+///
+/// - don't give up
+///     - just don't
+/// - don't give up
+///
+/// # Level 1
+/// ## Level 2
+/// ### Level 3
+/// #### Level 4
+/// ##### Level 5
+/// ###### Level 6
+///
+/// | Command | Description |
+/// | --- | --- |
+/// | `git status` | List all *new or modified* files |
+/// | `git diff` | Show file differences that **haven't been** staged |
+open module com.package1.classComments
+
+// Class with single-line code comment.
+class Comments1
+
+/*
+  Class with
+  multi-line
+  code comment.
+*/
+class Comments2
+
+/// Class with single-line doc comment.
+class Comments3
+
+/// Class with multi-line and multi-paragraph doc comment (paragraph1, line1).
+/// Class with multi-line and multi-paragraph doc comment (paragraph1, line2).
+///
+/// Class with multi-line and multi-paragraph doc comment (paragraph2, line1).
+/// Class with multi-line and multi-paragraph doc comment (paragraph2, line2).
+class Comments4
+
+/// Class with [single-line](https://apple.com) *Markdown* doc comment.
+class Comments5
+
+/// Class with
+/// [multi-line](https://apple.com)
+/// *Markdown* doc comment.
+class Comments6
+
+/// 😀😀😀 Class with 😎😎😎 Unicode doc comment. 😡😡😡
+class Comments7
+
+/// The greatest breakthrough since ever.
+///
+/// ## Installation
+///
+/// Just follow these simple steps:
+///
+/// 1. Install it
+///     1. I promise it's easy.
+///     2. You'll figure it out.
+/// 1. Install it
+///     ```
+///     name = "Pigeon"
+///     age = 42
+///     ```
+/// 1. Install it
+///
+/// Let me **emphasize** how *simple* this is.
+///
+/// 😀😀😀 emoji day 😎😎😎 don't get 😡😡😡
+///
+/// ## Code
+///
+/// The code is beautiful:
+///
+/// ```
+/// /// example module
+/// module foo.bar
+///
+/// person {
+///   name = "Pigeon"
+///   age = 42
+/// }
+///
+/// function sing() = "tra-la-la"
+///
+/// class Person {
+///   name: String
+///   age: Int
+/// }
+/// ```
+///
+/// ## Random Tips
+///
+/// - don't give up
+///     - just don't
+/// - don't give up
+///
+/// # Level 1
+/// ## Level 2
+/// ### Level 3
+/// #### Level 4
+/// ##### Level 5
+/// ###### Level 6
+class Comments8

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/classInheritance.pkl

@@ -0,0 +1,29 @@
+/// Class inheritance involving abstract, open, and final classes.
+module com.package1.classInheritance
+
+abstract class MyClass1 {
+  /// Inherited property comment.
+  abstract property1: Boolean
+
+  /// function method1 in class MyClass1.
+  abstract function method1(arg: String): Boolean
+}
+
+open class MyClass2 extends MyClass1 {
+  property1: Boolean = false
+  property2: String = ""
+
+  /// function method1 in class MyClass2.
+  function method1(arg: String): Boolean = Undefined()
+  function method2(arg: String): Boolean = Undefined()
+}
+
+abstract class MyClass3 extends MyClass2 {
+  property1: Boolean = true
+  function method1(arg: String): Boolean = Undefined()
+}
+
+class MyClass4 extends MyClass2 {
+  property4: String = ""
+  function method3(arg: String): Boolean = Undefined()
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/classMethodComments.pkl

@@ -0,0 +1,33 @@
+/// Class methods with different kinds of comments.
+module com.package1.classMethodComments
+
+class Comments {
+  // Method with single-line code comment.
+  function method1(): Float = Undefined()
+
+  /*
+    Method with
+    multi-line
+    code comment.
+  */
+  function method2(): Float = Undefined()
+
+  /// Method with single-line doc comment.
+  function method3(): Float = Undefined()
+
+  /// Method with
+  /// multi-line
+  /// doc comment.
+  function method4(): Float = Undefined()
+
+  /// Method with [single-line](https://apple.com) *Markdown* doc comment.
+  function method5(): Float = Undefined()
+
+  /// Method with
+  /// [multi-line](https://apple.com)
+  /// *Markdown* doc comment.
+  function method6(): Float = Undefined()
+
+  /// 😀😀😀 Method with 😎😎😎 Unicode doc comment. 😡😡😡
+  function method7(): Float = Undefined()
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/classMethodModifiers.pkl

@@ -0,0 +1,15 @@
+/// Class methods with different modifiers.
+module com.package1.classMethodModifiers
+
+abstract class Modifiers {
+  /// Method with `abstract` modifier.
+  abstract function method1(arg: String): Boolean
+
+  /*
+  /// Method with `external` modifier.
+  external function method2(arg: String): Boolean
+
+  /// Method with multiple modifiers.
+  abstract external function method3(arg: String): Boolean
+  */
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/classMethodTypeAnnotations.pkl

@@ -0,0 +1,43 @@
+/// Class methods with different kinds of type annotations.
+module com.package1.classMethodTypeAnnotations
+
+class TypeAnnotations {
+  /// Zero-arg method without declared types.
+  function method1() = Undefined()
+
+  /// One-arg method without declared types.
+  function method2(arg1) = Undefined()
+
+  /// Two-arg method without declared types.
+  function method3(arg1, arg2) = Undefined()
+
+  /// Zero-arg method with simple types.
+  function method4(): String = Undefined()
+
+  /// One-arg method with simple types.
+  function method5(arg1: Boolean): Int = Undefined()
+
+  /// Two-arg method with simple types.
+  function method6(arg1: Int, arg2: Float): Duration = Undefined()
+
+  /// Two-arg method with list types.
+  function method7(arg1: List<Int>, arg2: List<Float>): List<Duration> = Undefined()
+
+  /// Two-arg method with set types.
+  function method8(arg1: Set<Int>, arg2: Set<Float>): Set<Duration> = Undefined()
+
+  /// Two-arg method with map types.
+  function method9(arg1: Map<Int, Int>, arg2: Map<Float, Float>): Map<Duration, Duration> = Undefined()
+
+  /// Two-arg method with optional types.
+  function method10(arg1: Int?, arg2: Float?): Duration? = Undefined()
+
+  /// Two-arg method with function types.
+  function method11(arg1: () -> Int, arg2: (Int) -> Float): (Int, Float) -> Duration = Undefined()
+
+  /// Two-arg method with partially declared types.
+  function method12(arg1: String, arg2): Boolean = Undefined()
+
+  /// One-arg method with complex types.
+  function method13(arg1: Map<List<String?>?, (Boolean?) -> Map<Int, Float>>): Map<List<Duration?>?, (DataSize?) -> Map<Any, Number>> = Undefined()
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/classMethodTypeReferences.pkl

@@ -0,0 +1,28 @@
+/// Class methods whose types reference classes from
+/// the same module, a different module, and external modules.
+module com.package1.classMethodTypeReferences
+
+import "shared.pkl"
+
+import "../com.externalpackage/external1.pkl"
+
+import "../com.externalpackage/external2.pkl"
+
+class MyClass
+
+class TypeReferences {
+  /// Method with intra-module types.
+  function method1(arg1: MyClass, arg2: MyClass): MyClass = Undefined()
+
+  /// Method with inter-module types.
+  function method2(arg1: shared.MyClass, arg2: shared.MyClass): shared.MyClass = Undefined()
+
+  /// Method with external-module types.
+  function method3(arg1: external1.MyClass, arg2: external2.MyClass): List<external1.MyClass> = Undefined()
+
+  /// Method with intra-module, inter-module, and external-module types.
+  function method4(arg1: MyClass, arg2: shared.MyClass): external1.MyClass = Undefined()
+
+  /// Method with complex intra-module, inter-module, and external-module types.
+  function method5(arg1: MyClass?, arg2: Map<shared.MyClass, external1.MyClass>): (external1.MyClass) -> external2.MyClass = Undefined()
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/classPropertyAnnotations.pkl

@@ -0,0 +1,13 @@
+module com.package1.classPropertyAnnotations
+
+class UserDefinedAnnotation extends Annotation {
+  messageOpt: String?
+  messageReq: String
+}
+
+class ClassWithAnnotatedProperty {
+  @UserDefinedAnnotation {
+    messageReq = "Hi!"
+  }
+  propertyUserDefinedAnnotation: Int = 42
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/classPropertyComments.pkl

@@ -0,0 +1,33 @@
+/// Class properties with different kinds of comments.
+module com.package1.classPropertyComments
+
+class Comments {
+  // Property with single-line code comment.
+  property1: Float = 3.14159265359
+
+  /*
+    Property with
+    multi-line
+    code comment.
+  */
+  property2: Float = 3.14159265359
+
+  /// Property with single-line doc comment.
+  property3: Float = 3.14159265359
+
+  /// Property with
+  /// multi-line
+  /// doc comment.
+  property4: Float = 3.14159265359
+
+  /// Property with [single-line](https://apple.com) *Markdown* doc comment.
+  property5: Float = 3.14159265359
+
+  /// Property with
+  /// [multi-line](https://apple.com)
+  /// *Markdown* doc comment.
+  property6: Float = 3.14159265359
+
+  /// 😀😀😀 Property with 😎😎😎 Unicode doc comment. 😡😡😡
+  property7: Float = 3.14159265359
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/classPropertyModifiers.pkl

@@ -0,0 +1,21 @@
+/// Class properties with different modifiers.
+module com.package1.classPropertyModifiers
+
+abstract class Modifiers {
+  /// Property with `local` modifier.
+  local property1 = 3.14159265359
+
+  /// Property with `hidden` modifier.
+  hidden property2: Float = 3.14159265359
+
+  /// Property with `abstract` modifier.
+  abstract property3: Float
+
+  /// Property with multiple modifiers.
+  abstract hidden property4: Float
+
+  /*
+  /// Property with `external` modifier.
+  external property5: Float
+  */
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/classPropertyTypeAnnotations.pkl

@@ -0,0 +1,34 @@
+/// Class properties with different kinds of type annotations.
+module com.package1.classPropertyTypeAnnotations
+
+class TypeAnnotations {
+  /// Property without declared type.
+  property1 = 3.14159265359
+
+  /// Property with simple type.
+  property2: Float = 3.14159265359
+
+  /// Property with list type.
+  property3: List<String> = List("1", "2", "3")
+
+  /// Property with set type.
+  property4: Set<String> = Set("1", "2", "3")
+
+  /// Property with map type.
+  property5: Map<String, Duration> = Map("one", 1.s, "two", 2.min, "three", 3.h)
+
+  /// Property with optional type.
+  property6: String? = "string"
+
+  /// Property with zero-arg function type.
+  property7: () -> String = () -> "string"
+
+  /// Property with one-arg function type.
+  property8: (String) -> Int = (str) -> str.length
+
+  /// Property with two-arg function type.
+  property9: (String, String) -> Int = (str1, str2) -> str1.length + str2.length
+
+  /// Property with complex type.
+  property10: Map<List<String?>?, (Boolean?) -> Map<Int, Float>> = Map(List("str"), (b) -> Map(3, 3.0))
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/classPropertyTypeReferences.pkl

@@ -0,0 +1,38 @@
+/// Class properties whose types reference classes from
+/// the same module, a different module, and external modules.
+module com.package1.classPropertyTypeReferences
+
+import "shared.pkl"
+
+import "../com.externalpackage/external1.pkl"
+
+class MyClass
+
+class TypeReferences {
+  /// Property with intra-module simple type.
+  property1: MyClass = new MyClass {}
+
+  /// Property with inter-module list type.
+  property2: List<shared.MyClass> = List(new shared.MyClass {})
+
+  /// Property with external-module set type.
+  property3: Set<external1.MyClass> = Set(new external1.MyClass {})
+
+  /// Property with intra-module and inter-module map type.
+  property4: Map<MyClass, shared.MyClass> = Map(new MyClass {}, new shared.MyClass {})
+
+  /// Property with external-module optional type.
+  property5: external1.MyClass? = new external1.MyClass {}
+
+  /// Property with zero-arg intra-module function type.
+  property6: () -> MyClass = () -> new MyClass {}
+
+  /// Property with one-arg inter-module and external-module function type.
+  property7: (shared.MyClass) -> external1.MyClass = (myClass) -> new external1.MyClass {}
+
+  /// Property with two-arg intra-module, inter-module, and external-module function type.
+  property8: (MyClass, shared.MyClass) -> external1.MyClass = (myClass1, myClass2) -> new external1.MyClass {}
+
+  /// Property with intra-module mapping type.
+  property9: Mapping<String, MyClass>
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/classTypeConstraints.pkl

@@ -0,0 +1,24 @@
+module com.package1.classTypeConstraints
+
+class Person1 {
+  name: String(length >= 3)
+  address: Address(street != city)
+}
+
+emailAddress = (str) -> str.matches(Regex(#".+@.+"#))
+
+class Person2 {
+  email: String(emailAddress)
+}
+
+class Address {
+  street: String(!isEmpty)
+  city: String = "San Francisco"
+}
+
+class Project {
+  // constraint for element type of optional type
+  type: String(oneOf(List("open-source", "closed-source")))?
+  // constraints for map type and its constituent key/value types
+  contacts: Map<String(!isEmpty), String(emailAddress)>(length > 10, length < 20)
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/doc-package-info.pkl

@@ -0,0 +1,48 @@
+/// Docs for Package 1.
+///
+/// * [docLinks]
+/// * [docLinks.age]
+/// * [docLinks.sing()]
+/// * [docLinks.Person]
+/// * [docLinks.Person.name]
+/// * [docLinks.PersonList]
+///
+/// * [external1]
+/// * [external1.MyClass]
+@Deprecated { message = "com.package1 is deprecated" }
+amends "pkl:DocPackageInfo"
+
+import "docLinks.pkl"
+import "../com.externalpackage/external1.pkl"
+
+name = "com.package1"
+version = "1.2.3"
+importUri = "https://pkl.io/"
+authors {
+  "package1-publisher@group.apple.com"
+}
+sourceCode = "https://example.com/package1/"
+sourceCodeUrlScheme = "https://example.com/package1%{path}#L%{line}-L%{endLine}"
+issueTracker = "https://issues.apple.com/package1/"
+
+dependencies {
+  new {
+    name = "com.package2"
+    version = "4.5.6"
+    sourceCode = "https://example.com/package2/"
+  }
+  new {
+    name = "com.externalpackage"
+    version = "7.8.9"
+    sourceCode = "https://example.com/externalpackage/"
+    documentation = "https://example.com/docs/externalpackage/"
+  }
+  new {
+    name = "pkl"
+    // use fixed version to avoid churn in expected test outputs
+    version = "0.24.0"
+    sourceCode = "https://github.com/apple/pkl/blob/dev/stdlib/"
+    sourceCodeUrlScheme = "https://github.com/apple/pkl/blob/0.24.0/stdlib%{path}#L%{line}-L%{endLine}"
+    documentation = "https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/"
+  }
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/docExample.pkl

@@ -0,0 +1,13 @@
+@DocExample {
+  subjects {
+    "com.package1.docExampleSubject1"
+    "com.package1.docExampleSubject2"
+  }
+}
+module com.package1.docExample
+
+amends "docExampleSubject1.pkl"
+
+import "docExampleSubject2.pkl"
+
+x = docExampleSubject2.y

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/docExample2.pkl

@@ -0,0 +1,6 @@
+@DocExample { subjects { "com.package1.docExampleSubject1" } }
+module com.package1.docExample2
+
+amends "docExampleSubject1.pkl"
+
+x = 42

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/docExampleSubject1.pkl

@@ -0,0 +1,3 @@
+module com.package1.docExampleSubject1
+
+x: Int

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/docExampleSubject2.pkl

@@ -0,0 +1,3 @@
+module com.package1.docExampleSubject2
+
+y: Int

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/docLinks.pkl

@@ -0,0 +1,84 @@
+/// [external1], [external1.MyClass]
+/// [shared], [shared.MyClass]
+/// [age], [sing()], [Person], [Person.name], [Person.call()], [PersonList]
+/// [docLinks], [docLinks.age], [docLinks.sing()],
+/// [docLinks.Person], [docLinks.Person.name], [docLinks.PersonList],
+/// [custom *link* text][docLinks.sing()]
+/// [module], [module.age], [module.sing()],
+/// [module.Person], [module.Person.name], [module.PersonList],
+/// [custom *link* text][module.sing()]
+module com.package1.docLinks
+
+import "../com.externalpackage/external1.pkl"
+import "shared.pkl"
+import "docLinks.pkl"
+
+/// [external1], [external1.MyClass]
+/// [shared], [shared.MyClass]
+/// [age], [sing()], [Person], [Person.name], [Person.call()], [PersonList]
+/// [docLinks], [docLinks.age], [docLinks.sing()],
+/// [docLinks.Person], [docLinks.Person.name], [docLinks.PersonList],
+/// [custom *link* text][docLinks.sing()]
+/// [module], [module.age], [module.sing()],
+/// [module.Person], [module.Person.name], [module.PersonList],
+/// [custom *link* text][module.sing()]
+age: Int
+
+/// [external1], [external1.MyClass]
+/// [shared], [shared.MyClass]
+/// [age], [sing()], [Person], [Person.name], [Person.call()], [PersonList]
+/// [docLinks], [docLinks.age], [docLinks.sing()],
+/// [docLinks.Person], [docLinks.Person.name], [docLinks.PersonList],
+/// [custom *link* text][docLinks.sing()]
+/// [module], [module.age], [module.sing()],
+/// [module.Person], [module.Person.name], [module.PersonList],
+/// [custom *link* text][module.sing()]
+/// [song]
+function sing(song: String) = "tra-la-la"
+
+/// [external1], [external1.MyClass]
+/// [shared], [shared.MyClass]
+/// [age], [sing()], [Person], [Person.name], [Person.call()], [Person.call()], [PersonList]
+/// [docLinks], [docLinks.age], [docLinks.sing()],
+/// [docLinks.Person], [docLinks.Person.name], [docLinks.PersonList],
+/// [custom *link* text][docLinks.sing()]
+/// [module], [module.age], [module.sing()],
+/// [module.Person], [module.Person.name], [module.PersonList],
+/// [custom *link* text][module.sing()]
+/// [name], [call()]
+class Person {
+  /// [external1], [external1.MyClass]
+  /// [age], [sing()], [Person], [Person.name], [Person.call()], [PersonList]
+  /// [docLinks], [docLinks.age], [docLinks.sing()],
+  /// [docLinks.Person], [docLinks.Person.name], [docLinks.PersonList],
+  /// [custom *link* text][docLinks.sing()]
+  /// [module], [module.age], [module.sing()],
+  /// [module.Person], [module.Person.name], [module.PersonList],
+  /// [custom *link* text][module.sing()]
+  /// [name], [call()]
+  name: String
+
+  /// [external1], [external1.MyClass]
+  /// [shared], [shared.MyClass]
+  /// [age], [sing()], [Person], [Person.name], [Person.call()], [PersonList]
+  /// [docLinks], [docLinks.age], [docLinks.sing()],
+  /// [docLinks.Person], [docLinks.Person.name], [docLinks.PersonList],
+  /// [custom *link* text][docLinks.sing()]
+  /// [module], [module.age], [module.sing()],
+  /// [module.Person], [module.Person.name], [module.PersonList],
+  /// [custom *link* text][module.sing()]
+  /// [name], [call()]
+  /// [number]
+  function call(number: String) = "calling $number"
+}
+
+/// [external1], [external1.MyClass]
+/// [shared], [shared.MyClass]
+/// [age], [sing()], [Person], [Person.name], [Person.call()], [PersonList]
+/// [docLinks], [docLinks.age], [docLinks.sing()],
+/// [docLinks.Person], [docLinks.Person.name], [docLinks.PersonList],
+/// [custom *link* text][docLinks.sing()]
+/// [module], [module.age], [module.sing()],
+/// [module.Person], [module.Person.name], [module.PersonList],
+/// [custom *link* text][module.sing()]
+typealias PersonList = List<Person>

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/methodAnnotations.pkl

@@ -0,0 +1,31 @@
+module com.package1.methodAnnotations
+
+/// This [mthod()] thought to have a correctly spelled name.
+@Deprecated {
+  message = "Spelling mistake."
+  replaceWith = "method()"
+}
+@AlsoKnownAs {
+  names { "function" }
+}
+function mthod(): Int = 42
+
+
+/// This [mthod()] thought to have a correctly spelled name.
+///
+/// Unfortunately, it did not, as we explain in this expandable comment.
+@Deprecated {
+  message = "Spelling mistake."
+  replaceWith = "method()"
+}
+@AlsoKnownAs {
+  names { "function" }
+}
+function mthodWithExpandableComment(): Int = 42
+
+
+// This [method()] indeed has a properly spelled name, but no doc comment.
+@AlsoKnownAs {
+  names { "function" }
+}
+function method(): Int = 42

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/moduleComments.pkl

@@ -0,0 +1,54 @@
+/// The greatest breakthrough since ever.
+///
+/// ### Installation
+///
+/// Just follow these simple steps:
+///
+/// 1. Install it
+///     1. I promise it's easy.
+///     2. You'll figure it out.
+/// 1. Install it
+///     ```
+///     name = "Pigeon"
+///     age = 42
+///     ```
+/// 1. Install it
+///
+/// Let me **emphasize** how *simple* this is.
+///
+/// 😀😀😀 emoji day 😎😎😎 don't get 😡😡😡
+///
+/// ### Code
+///
+/// The code is beautiful:
+///
+/// ```
+/// /// example module
+/// module foo.bar
+///
+/// person {
+///   name = "Pigeon"
+///   age = 42
+/// }
+///
+/// function sing() = "tra-la-la"
+///
+/// class Person {
+///   name: String
+///   age: Int
+/// }
+/// ```
+///
+/// ### Random Tips
+///
+/// - don't give up
+///     - just don't
+/// - don't give up
+///
+/// # Level 1
+/// ## Level 2
+/// ### Level 3
+/// #### Level 4
+/// ##### Level 5
+/// ###### Level 6
+module com.package1.moduleComments

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/moduleExtend.pkl

@@ -0,0 +1,9 @@
+module com.package1.moduleExtend
+
+extends "baseModule.pkl"
+
+extendProperty = 42
+
+function extendMethod() = 42
+
+class ExtendClass {}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/moduleInfoAnnotation.pkl

@@ -0,0 +1,2 @@
+@ModuleInfo { minPklVersion = "0.10.0" }
+module com.package1.moduleInfoAnnotation

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/moduleMethodCommentInheritance.pkl

@@ -0,0 +1,5 @@
+module com.package1.moduleMethodCommentInheritance
+
+extends "moduleMethodComments.pkl"
+
+function method3(arg: String): Boolean = Undefined()

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/moduleMethodComments.pkl

@@ -0,0 +1,31 @@
+/// Module methods with different kinds of comments.
+open module com.package1.moduleMethodComments
+
+// Method with single-line code comment.
+function method1(): Float = Undefined()
+
+/*
+  Method with
+  multi-line
+  code comment.
+*/
+function method2(): Float = Undefined()
+
+/// Method with single-line doc comment.
+function method3(): Float = Undefined()
+
+/// Method with
+/// multi-line
+/// doc comment.
+function method4(): Float = Undefined()
+
+/// Method with [single-line](https://apple.com) *Markdown* doc comment.
+function method5(): Float = Undefined()
+
+/// Method with
+/// [multi-line](https://apple.com)
+/// *Markdown* doc comment.
+function method6(): Float = Undefined()
+
+/// 😀😀😀 Method with 😎😎😎 Unicode doc comment. 😡😡😡
+function method7(): Float = Undefined()

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/moduleMethodModifiers.pkl

@@ -0,0 +1,13 @@
+/// Module methods with different modifiers.
+module com.package1.moduleMethodModifiers
+
+/// Method with `abstract` modifier.
+abstract function method1(arg: String): Boolean
+
+/*
+/// Method with `external` modifier.
+external function method2(arg: String): Boolean
+
+/// Method with multiple modifiers.
+abstract external function method3(arg: String): Boolean
+*/

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/moduleMethodTypeAnnotations.pkl

@@ -0,0 +1,41 @@
+/// Module methods with different kinds of type annotations.
+module com.package1.moduleMethodTypeAnnotations
+
+/// Zero-arg method without declared types.
+function method1() = Undefined()
+
+/// One-arg method without declared types.
+function method2(arg1) = Undefined()
+
+/// Two-arg method without declared types.
+function method3(arg1, arg2) = Undefined()
+
+/// Zero-arg method with simple types.
+function method4(): String = Undefined()
+
+/// One-arg method with simple types.
+function method5(arg1: Boolean): Int = Undefined()
+
+/// Two-arg method with simple types.
+function method6(arg1: Int, arg2: Float): Duration = Undefined()
+
+/// Two-arg method with list types.
+function method7(arg1: List<Int>, arg2: List<Float>): List<Duration> = Undefined()
+
+/// Two-arg method with set types.
+function method8(arg1: Set<Int>, arg2: Set<Float>): Set<Duration> = Undefined()
+
+/// Two-arg method with map types.
+function method9(arg1: Map<Int, Int>, arg2: Map<Float, Float>): Map<Duration, Duration> = Undefined()
+
+/// Two-arg method with optional types.
+function method10(arg1: Int?, arg2: Float?): Duration? = Undefined()
+
+/// Two-arg method with function types.
+function method11(arg1: () -> Int, arg2: (Int) -> Float): (Int, Float) -> Duration = Undefined()
+
+/// Two-arg method with partially declared types.
+function method12(arg1: String, arg2): Boolean = Undefined()
+
+/// One-arg method with complex types.
+function method13(arg1: Map<List<String?>?, (Boolean?) -> Map<Int, Float>>): Map<List<Duration?>?, (DataSize?) -> Map<Any, Number>> = Undefined()

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/moduleMethodTypeReferences.pkl

@@ -0,0 +1,26 @@
+/// Module methods whose types reference classes from
+/// the same module, a different module, and external modules.
+module com.package1.moduleMethodTypeReferences
+
+import "shared.pkl"
+
+import "../com.externalpackage/external1.pkl"
+
+import "../com.externalpackage/external2.pkl"
+
+class MyClass
+
+/// Method with intra-module types.
+function method1(arg1: MyClass, arg2: MyClass): MyClass = Undefined()
+
+/// Method with inter-module types.
+function method2(arg1: shared.MyClass, arg2: shared.MyClass): shared.MyClass = Undefined()
+
+/// Method with external-module types.
+function method3(arg1: external1.MyClass, arg2: external2.MyClass): List<external1.MyClass> = Undefined()
+
+/// Method with intra-module, inter-module, and external-module types.
+function method4(arg1: MyClass, arg2: shared.MyClass): external1.MyClass = Undefined()
+
+/// Method with complex intra-module, inter-module, and external-module types.
+function method5(arg1: MyClass?, arg2: Map<shared.MyClass, external1.MyClass>): (external1.MyClass) -> external2.MyClass = Undefined()

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/modulePropertyAnnotations.pkl

@@ -0,0 +1,77 @@
+module com.package1.modulePropertyAnnotations
+
+/// This [prperty] thought to have a correctly spelled name.
+@Deprecated {
+  message = "Spelling mistake."
+  replaceWith = "property"
+}
+@AlsoKnownAs {
+  names { "field"; "item" }
+}
+hidden prperty = 42
+
+
+/// This [prperty] thought to have a correctly spelled name.
+///
+/// Unfortunately, it did not, as we explain in this expandable comment.
+@Deprecated {
+  message = "Spelling mistake."
+  replaceWith = "property"
+}
+@AlsoKnownAs {
+  names { "field"; "item" }
+}
+hidden prpertyWithExpandableComment = 42
+
+
+// This [property] indeed has a properly spelled name, but no doc comment.
+@AlsoKnownAs {
+  names { "field"; "item" }
+}
+hidden property = 42
+
+
+
+
+class UserDefinedAnnotation extends Annotation {
+  messageOpt: String?
+  messageReq: String
+}
+
+@UserDefinedAnnotation {
+  messageReq = "Hi!"
+}
+propertyUserDefinedAnnotation: Int = 42
+
+
+
+
+class UserDefinedAnnotation1 extends Annotation {
+  nested: UserDefinedAnnotation
+}
+
+@UserDefinedAnnotation1 {
+  nested = new UserDefinedAnnotation {
+    messageReq = "Hi!"
+  }
+}
+propertyUserDefinedAnnotation1: Int = 42
+
+
+
+
+class UserDefinedAnnotation2 extends Annotation {
+  nested: UserDefinedAnnotation2?
+}
+
+@UserDefinedAnnotation2 {
+  nested = new UserDefinedAnnotation2 {
+    nested = new UserDefinedAnnotation2 {
+      nested = new UserDefinedAnnotation2 {
+        nested = new UserDefinedAnnotation2 {
+        }
+      }
+    }
+  }
+}
+propertyUserDefinedAnnotation2: Int = 42

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/modulePropertyCommentInheritance.pkl

@@ -0,0 +1,5 @@
+module com.package1.modulePropertyCommentInheritance
+
+extends "modulePropertyComments.pkl"
+
+property3: Float = 1.23

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/modulePropertyComments.pkl

@@ -0,0 +1,54 @@
+/// Module properties with different kinds of comments.
+open module com.package1.modulePropertyComments
+
+// Property with single-line code comment.
+property1: Float = 3.14159265359
+
+/*
+  Property with
+  multi-line
+  code comment.
+*/
+property2: Float = 3.14159265359
+
+/// Property with single-line doc comment.
+property3: Float = 3.14159265359
+
+/// Property with
+/// multi-line
+/// doc comment.
+property4: Float = 3.14159265359
+
+/// Property with [single-line](https://apple.com) *Markdown* doc comment.
+property5: Float = 3.14159265359
+
+/// Property with
+/// [multi-line](https://apple.com)
+/// *Markdown* doc comment.
+property6: Float = 3.14159265359
+
+/// 😀😀😀 Property with 😎😎😎 Unicode doc comment. 😡😡😡
+property7: Float = 3.14159265359
+
+/// Summary
+/// ```
+/// 
+/// code = 4 * 10
+/// ```
+/// Rest of the body
+property8: Int = 0
+
+/// Sumary
+/// ```java
+/// 
+/// code = 0
+/// ```
+/// Rest
+property9: Int = 1
+
+/// ```
+/// 
+/// code = 2
+/// ```
+/// Rest
+property10: Int = 2

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/modulePropertyModifiers.pkl

@@ -0,0 +1,19 @@
+/// Module properties with different modifiers.
+module com.package1.modulePropertyModifiers
+
+/// Property with `local` modifier.
+local property1 = 3.14159265359
+
+/// Property with `hidden` modifier.
+hidden property2: Float = 3.14159265359
+
+/*
+/// Property with `external` modifier.
+external property3: Float
+
+/// Property with `abstract` modifier.
+abstract property4: Float
+
+/// Property with multiple modifiers.
+abstract external hidden property5: Float
+*/

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/modulePropertyTypeAnnotations.pkl

@@ -0,0 +1,32 @@
+/// Module properties with different kinds of type annotations.
+module com.package1.modulePropertyTypeAnnotations
+
+/// Property without declared type.
+property1 = 3.14159265359
+
+/// Property with simple type.
+property2: Float = 3.14159265359
+
+/// Property with list type.
+property3: List<String> = List("1", "2", "3")
+
+/// Property with set type.
+property4: Set<String> = Set("1", "2", "3")
+
+/// Property with map type.
+property5: Map<String, Duration> = Map("one", 1.s, "two", 2.min, "three", 3.h)
+
+/// Property with optional type.
+property6: String? = "string"
+
+/// Property with zero-arg function type.
+property7: () -> String = () -> "string"
+
+/// Property with one-arg function type.
+property8: (String) -> Int = (str) -> str.length
+
+/// Property with two-arg function type.
+property9: (String, String) -> Int = (str1, str2) -> str1.length + str2.length
+
+/// Property with complex type.
+property10: Map<List<String?>?, (Boolean?) -> Map<Int, Float>> = Map(List("str"), (b) -> Map(3, 3.0))

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/modulePropertyTypeReferences.pkl

@@ -0,0 +1,36 @@
+/// Module properties whose types reference classes from
+/// the same module, a different module, and external modules.
+module com.package1.modulePropertyTypeReferences
+
+import "shared.pkl"
+
+import "../com.externalpackage/external1.pkl"
+
+class MyClass
+
+/// Property with intra-module simple type.
+property1: MyClass = new MyClass {}
+
+/// Property with inter-module list type.
+property2: List<shared.MyClass> = List(new shared.MyClass {})
+
+/// Property with external-module set type.
+property3: Set<external1.MyClass> = Set(new external1.MyClass {})
+
+/// Property with intra-module and inter-module map type.
+property4: Map<MyClass, shared.MyClass> = Map(new MyClass {}, new shared.MyClass {})
+
+/// Property with external-module optional type.
+property5: external1.MyClass? = new external1.MyClass {}
+
+/// Property with zero-arg intra-module function type.
+property6: () -> MyClass = () -> new MyClass {}
+
+/// Property with one-arg inter-module and external-module function type.
+property7: (shared.MyClass) -> external1.MyClass = (myClass) -> new external1.MyClass {}
+
+/// Property with two-arg intra-module, inter-module, and external-module function type.
+property8: (MyClass, shared.MyClass) -> external1.MyClass = (myClass1, myClass2) -> new external1.MyClass {}
+
+/// Property with intra-module mapping type.
+property9: Mapping<String, MyClass>

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/moduleTypes1.pkl

@@ -0,0 +1,3 @@
+module com.package1.moduleTypes1
+
+n: Int

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/moduleTypes2.pkl

@@ -0,0 +1,37 @@
+module com.package1.moduleTypes2
+
+import "moduleTypes1.pkl"
+
+x1: moduleTypes1
+
+x2: moduleTypes1?
+
+x3: Listing<moduleTypes1>
+
+x4: Mapping<moduleTypes1, moduleTypes1>
+
+x5: String|moduleTypes1|Int
+
+x6: module
+
+x7: List<module>
+
+x8: String|module|Int
+
+class Foo {
+  x1: moduleTypes1
+
+  x2: moduleTypes1?
+
+  x3: Listing<moduleTypes1>
+
+  x4: Mapping<moduleTypes1, moduleTypes1>
+
+  x5: String|moduleTypes1|Int
+
+  x6: module
+
+  x7: List<module>
+
+  x8: String|module|Int
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/nested/nested2/nestedModule.pkl

@@ -0,0 +1,7 @@
+module com.package1.nested.nested2.nestedModule
+
+myProperty = 42
+
+function myMethod() = 42
+
+class MyClass {}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/shared.pkl

@@ -0,0 +1,3 @@
+module com.package1.shared
+
+class MyClass

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/typeAliases.pkl

@@ -0,0 +1,31 @@
+open module com.package1.typealiases
+
+/// A [String] representing an [Email] address.
+@AlsoKnownAs { names { "OtherName" } }
+typealias Email = String(contains("@"))
+
+uint: UInt
+
+uints: List<UInt>
+
+/// My [Email].
+email: Email
+
+emails: List<Email>
+
+/// Sends an [Email].
+function send(email: Email): Email = "abc"
+
+open class Person {
+  uint: UInt
+
+  list: List<UInt>
+
+  /// A person's [Email].
+  email: Email
+
+  emails: List<Email>
+
+  /// Sends an [Email].
+  function send(email: Email): Email = "abc"
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/typeAliases2.pkl

@@ -0,0 +1,32 @@
+module com.package1.typealiases2
+
+class Person { name: String }
+
+typealias List2<E> = List<E>
+typealias Map2<V, K> = Map<K, V>
+typealias StringMap<V> = Map<String, V>
+typealias MMap<X> = Map<X, X>
+
+res1: List2<Int>
+res2: List2<List2<String>>
+res3: Map2<String, Int>
+res4: StringMap<Duration>
+res5: MMap<Person?>
+
+res6: List2
+res7: Map2
+res8: StringMap
+res9: MMap
+
+class Foo {
+  res1: List2<Int>
+  res2: List2<List2<String>>
+  res3: Map2<String, Int>
+  res4: StringMap<Duration>
+  res5: MMap<Person?>
+
+  res6: List2
+  res7: Map2
+  res8: StringMap
+  res9: MMap
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/typeAliasesInheritance.pkl

@@ -0,0 +1,13 @@
+module com.package1.typeAliasInheritance
+
+extends "typeAliases.pkl"
+
+email2: Email
+
+emails2: List<Email>
+
+class Person2 extends Person {
+  email2: Email
+
+  emails2: List<Email>
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/unionTypes.pkl

@@ -0,0 +1,13 @@
+module com.package1.unionTypes
+
+res1: Boolean|Number
+
+res2: "foo"|"bar"|"baz"
+
+res3: Boolean|List<String>
+
+res4: Boolean|List<String>?
+
+res5: (Boolean|List<String>)?
+
+res6: (Boolean|List<String>)?|Number

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/unlistedClass.pkl

@@ -0,0 +1,8 @@
+module com.package1.unlistedClass
+
+myProperty = 42
+
+function myMethod() = 42
+
+@Unlisted
+class MyClass {}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/unlistedMethod.pkl

@@ -0,0 +1,8 @@
+module com.package1.unlistedMethod
+
+myProperty = 42
+
+@Unlisted
+function myMethod() = 42
+
+class MyClass {}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/unlistedModule.pkl

@@ -0,0 +1,8 @@
+@Unlisted
+module com.package1.unlistedModule
+
+myProperty = 42
+
+function myMethod() = 42
+
+class MyClass {}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package1/unlistedProperty.pkl

@@ -0,0 +1,8 @@
+module com.package1.unlistedProperty
+
+@Unlisted
+myProperty = 42
+
+function myMethod() = 42
+
+class MyClass {}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package2/Module3.pkl

@@ -0,0 +1,11 @@
+module com.package2.Module3
+
+property3: String
+
+function function3(n: Int): String = n.toString()
+
+class Class3 {
+  property3: String
+
+  function function3(n: Int): String = n.toString()
+}

pkl-doc/src/test/files/DocGeneratorTest/input/com.package2/doc-package-info.pkl

@@ -0,0 +1,23 @@
+/// Docs for Package 2.
+amends "pkl:DocPackageInfo"
+
+name = "com.package2"
+version = "4.5.6"
+importUri = "modulepath:/com/package2/"
+authors {
+  "package2-publisher@group.apple.com"
+}
+sourceCode = "https://sources.apple.com/package2/"
+sourceCodeUrlScheme = "https://example.com/blob/\(version)%{path}#L%{line}-L%{endLine}"
+issueTracker = "https://issues.apple.com/package2/"
+
+dependencies {
+  new {
+    name = "pkl"
+    // use fixed version to avoid churn in expected test outputs
+    version = "0.24.0"
+    sourceCode = "https://github.com/apple/\(name)/blob/dev/stdlib/"
+    sourceCodeUrlScheme = "https://github.com/apple/\(name)/blob/\(version)/stdlib%{path}#L%{line}-L%{endLine}"
+    documentation = "https://pkl-lang.org/stdlib/\(name)/\(version)/"
+  }
+}

pkl-doc/src/test/files/DocGeneratorTest/input/docsite-info.pkl

@@ -0,0 +1,65 @@
+/// Let the games begin.
+///
+/// ## Great Library
+///
+/// Just follow these simple steps. You'll love it.
+///
+/// 1. Install it
+/// 1. I promise it's easy.
+/// 2. You'll figure it out.
+/// 1. Install it
+/// ```
+/// name = "Pigeon"
+/// age = 42
+/// ```
+/// 1. Install it
+///
+/// Let me **emphasize** how *simple* this is.
+///
+/// 😀😀😀 emoji day 😎😎😎 don't get 😡😡😡
+///
+/// ## Code
+///
+/// The code is beautiful:
+///
+/// ```
+/// /// example module
+/// module foo.bar
+///
+/// person {
+/// name = "Pigeon"
+/// age = 42
+/// }
+///
+/// function sing() = "tra-la-la"
+///
+/// class Person {
+/// name: String
+/// age: Int
+/// }
+/// ```
+///
+/// ## Random Tips
+///
+/// - don't give up
+/// - just don't
+/// - don't give up
+///
+/// # Level 1
+/// ## Level 2
+/// ### Level 3
+/// #### Level 4
+/// ##### Level 5
+/// ###### Level 6
+///
+/// * [docLinks]
+/// * [docLinks.age]
+/// * [docLinks.sing()]
+/// * [docLinks.Person]
+/// * [docLinks.Person.name]
+/// * [docLinks.PersonList]
+amends "pkl:DocsiteInfo"
+
+import "com.package1/docLinks.pkl"
+
+title = "Docsite Title"