From 840662b0ae3ec8da7d7c42e9293a2717aa669699 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:15:47 +0800 Subject: [PATCH 01/22] Add RFC for docstring syntax --- rfcs/0001-doctring-syntax.md | 222 +++++++++++++++++++++++++++++++++ rfcs/0001-doctring-syntax.typ | 227 ++++++++++++++++++++++++++++++++++ 2 files changed, 449 insertions(+) create mode 100644 rfcs/0001-doctring-syntax.md create mode 100644 rfcs/0001-doctring-syntax.typ diff --git a/rfcs/0001-doctring-syntax.md b/rfcs/0001-doctring-syntax.md new file mode 100644 index 0000000..ee461e2 --- /dev/null +++ b/rfcs/0001-doctring-syntax.md @@ -0,0 +1,222 @@ +- Feature Name: `docstring` +- Start Date: 2025-09-13 +- RFC PR: [typst-community/rfcs#6](https://github.com/typst-community/rfcs/pull/6) +- Typst Issue: None + +## Summary + +This RFC discusses the syntax for docstrings in Typst. A docstring is an item in the source code that holds the documentation of one or multiple language items. + +## Motivation + +People need to be able to write documentation over language items for their packages. + +## The language items that can be documented + +This section lists the possible language items that can be documented. Until typst v0.13.1: + +- Let bindings. For example, `id` in the following example. + ```typ + /// A function that constantly returns its input. + #let id(x) = x + ``` + +- Modules (Files). For example, the file itself. + ```typ + /// The file itself is documented by the first line of the file. + ``` + +- Destructed variables. For example, `a` and `b` in the following example. + ```typ + /// Swaps the values of two variables. + /// + /// - `a`: The first element of the tuple. + /// - `b`: The second element of the tuple. + #let (a, b) = (b, a) + ``` + +- Parameters. For example, `x` and `y` in the following example. + ```typ + /// A function that swaps the values of two variables. + /// + /// - `x`: The first variable to swap. + /// - `y`: The second variable to swap. + #let swap(x, y) = (y, x) + ``` + +- Other Expressions. For example, the show rule in the following example. + ```typ + /// A show rule that does nothing. + #show: it => it + ``` + +### The reader of docstrings + +The reader of docstrings are the _docstring processors_. + +- documentation tools, like `tidy`. +- analyzers and test frameworks, like `typst-ide`, `tinymist`, and `tytanic`. + +## Existing docstring styles + +This section lists the existing docstring styles. Languages put documentation in comments or real strings in specific locations. The comments holding the documentation are usually called doc comments. + +### JsDoc-style + +Javscript and Typescript use JsDoc-style docstrings. + +For example: + +```js +/** + * A function that swaps the values of two variables. + * + * @param {number} x - The first variable to swap. + * @param {number} y - The second variable to swap. + * @returns {number[]} The swapped values. + */ +function swap(x, y) { + return [y, x]; +} +``` + +- The documentation are written within a single block comment. +- The each line of the block comment CAN be prefixed with `*` and stripped by the docstring processor. +- The annotations are written within `@param` and `@returns` tags. +- The documentation are written in Markdown format. + +### Rust-style + +Rust uses Rust-style docstrings. + +For example: + +```rs +/// A function that swaps the values of two variables. +/// +/// # Arguments +/// +/// * `x` - The first variable to swap. +/// * `y` - The second variable to swap. +/// +/// # Returns +/// +/// The swapped values. +fn swap(x: i32, y: i32) -> (i32, i32) { + (y, x) +} +``` + +- The documentation are written within consecutive lines of the line comments. +- Each line of the documentation MUST be prefixed with `///`. +- The parameters cannot be documented with special syntax. +- The documentation are written in Markdown format. + +### Python-style + +Python uses Python-style doc comments. + +For example: + +```py +def swap(x, y): + """ + A function that swaps the values of two variables. + """ + return y, x +``` + +- The documentation are written within a "dead" long string at the start of the function body. +- The parameters cannot be documented with special syntax. +- The documentation are written in Markdown format. + +## Issue 1: The syntax of the content of docstrings + +In previous discussion, Markdown Syntax and Typst Syntax are taken into considerations. laurmaedje and people all believes that docstrings should use Typst syntax. + +### Issue 1.1: docstrings with compile errors + +While a docstring has compile errors, it SHOULD be tolerated when rendering the docstring. Two main reasons can cause "sensible" undefined references: + +- processor-specific definitions: _Docstring processors_ can add unique definitions to the scope of a docstring. For example, `example` function is defined by tidy, however, it can be not defined by the official docstring processor. +- definitions in the package to render examples: A common case is that developer would like to create examples with the current definitions provided by the package. However, a definition may be invalid when the developer is editing the code. It is not good if docstrings are not rendered during editing. +- backward compatibility issue: people may use an older version of some _docstring processor_ and definitions are not provided in the older version. + +The above example indicates that, only a subset of typst syntax is suggested to be used in docstrings, to allow rendering and parsing with compile errors. + +### Issue 1.2: Compile docstrings with external defintions + +In Issue 1.1, we mentioned that _Docstring processors_ and developers can add definitions to the scope of a docstring. The definitions from the documented package is particularly concerned. We can catergorize the definitions by their visibility: + +- Definitions provided by other packages: the definitions defined by the entry file of a package. +- Definitions provided by other files in the same workspace: the definitions from other files in the same workspace. +- Definitions provided by the current files: the public definitions defined in the current file. In particular, a docstring may access the successor public definitions while is not yet defined while processing the docstring. In particular, a definition can be gone temporarily if a developer is editing the code. +- Private definitions: some definitions may be used or documented, while they are not public or re-exported. for example: + ````typ + #let new() = { + /// Configures the package. + /// ```example + /// configure() + /// ``` + let configure() = todo() + /// Runs the package. + /// ```example + /// configure() + /// run() + /// ``` + let run() = todo() + + return r( + configure: configure, + run: run, + )un + } + #let pkg = new() + ```` + +### Issue 1.3: Compile docstrings with processor-specific show rules + +Docstring processors may define special show rules to render docstrings. For example, tidy 0.3.0 defines a show rule to render examples: + +```typ +#show raw.where(lang: "exmaple"): render-example +``` + +A docstring processor SHOULD not introduce a show rule if some docstring cannot be rendered without the show rule. + +### Issue 2: The syntax of doc comments + +The python-style is not suitable for Typst, so we may only consider putting documentation in comments. However, it is not yet decided how doc comments should be written. + +#### Issue 2.1: block comments + +Rust doesn't allow block comments as doc comments. It is also not suitable for Typst. At least the `*` prefix used by js-doc style is a valid prefix for block comments. + +#### Issue 2.2: The place of doc comments + +Rust strictly enforces the placement of doc comments. The "Other Expressions" are not allowed to have doc comments. Doc comments of rust CANNOT be placed in a parameter list. + +#### Issue 2.3: Module-level doc comments + +Rust prefixes module-level doc comments with `//!`. The syntax of module-level doc comments should consider other plain comments at the start of the file. + +- shebang: `#!`. Luckily, it is not a valid comment in Typst. +- commented code: A package owner may commented out some code and they may be identified as a module-level doc comment. +- license: A package owner may would like to add a license at the start of the file and before the module-level doc comments. For example: + ```typ + // SPDX-License-Identifier: MIT + /// The file itself is documented by the first line of the file. + ``` + The package owner may not expect the license to be rendered in the documentation. + +## Existing Design + +[tinymist.](https://myriad-dreamin.github.io/tinymist/feature/docs.html) + +- A doc comment can be started with either `///` or `//` and the comments with same prefix are grouped together as a a single docstring. This is a loosed syntax because of Issue 2: the syntax of doc comments is not yet decided. +- The docstring is in typst syntax and a docstring can only access the public definitions provided by the current package, if it is in a package. +- The valid places are limited to only before "Let bindings" and at the start of the "Modules" (Files), to ensure simple migration to official syntax in future. + +## Unresolved questions + +All of above issues are unresolved questions. diff --git a/rfcs/0001-doctring-syntax.typ b/rfcs/0001-doctring-syntax.typ new file mode 100644 index 0000000..60f19ac --- /dev/null +++ b/rfcs/0001-doctring-syntax.typ @@ -0,0 +1,227 @@ +#let rfcs(num) = link("https://github.com/typst-community/rfcs/pull/" + str(num))[typst-community/rfcs\##num] +- Feature Name: `docstring` +- Start Date: 2025-09-13 +- RFC PR: #rfcs(6) +- Typst Issue: None + += Summary + +This RFC discusses the syntax for docstrings in Typst. A docstring is an item in the source code that holds the documentation of one or multiple language items. + += Motivation + +People need to be able to write documentation over language items for their packages. + += The language items that can be documented + +This section lists the possible language items that can be documented. Until typst v0.13.1: + +- Let bindings. For example, `id` in the following example. + + ```typ + /// A function that constantly returns its input. + #let id(x) = x + ``` + +- Modules (Files). For example, the file itself. + + ```typ + /// The file itself is documented by the first line of the file. + ``` + +- Destructed variables. For example, `a` and `b` in the following example. + + ```typ + /// Swaps the values of two variables. + /// + /// - `a`: The first element of the tuple. + /// - `b`: The second element of the tuple. + #let (a, b) = (b, a) + ``` + +- Parameters. For example, `x` and `y` in the following example. + + ```typ + /// A function that swaps the values of two variables. + /// + /// - `x`: The first variable to swap. + /// - `y`: The second variable to swap. + #let swap(x, y) = (y, x) + ``` + +- Other Expressions. For example, the show rule in the following example. + + ```typ + /// A show rule that does nothing. + #show: it => it + ``` + +== The reader of docstrings + +The reader of docstrings are the _docstring processors_. +- documentation tools, like `tidy`. +- analyzers and test frameworks, like `typst-ide`, `tinymist`, and `tytanic`. + += Existing docstring styles + +This section lists the existing docstring styles. Languages put documentation in comments or real strings in specific locations. The comments holding the documentation are usually called doc comments. + +== JsDoc-style + +Javscript and Typescript use JsDoc-style docstrings. + +For example: + +```js +/** + * A function that swaps the values of two variables. + * + * @param {number} x - The first variable to swap. + * @param {number} y - The second variable to swap. + * @returns {number[]} The swapped values. + */ +function swap(x, y) { + return [y, x]; +} +``` + +- The documentation are written within a single block comment. +- The each line of the block comment CAN be prefixed with `*` and stripped by the docstring processor. +- The annotations are written within `@param` and `@returns` tags. +- The documentation are written in Markdown format. + +== Rust-style + +Rust uses Rust-style docstrings. + +For example: + +```rs +/// A function that swaps the values of two variables. +/// +/// # Arguments +/// +/// * `x` - The first variable to swap. +/// * `y` - The second variable to swap. +/// +/// # Returns +/// +/// The swapped values. +fn swap(x: i32, y: i32) -> (i32, i32) { + (y, x) +} +``` + +- The documentation are written within consecutive lines of the line comments. +- Each line of the documentation MUST be prefixed with `///`. +- The parameters cannot be documented with special syntax. +- The documentation are written in Markdown format. + +== Python-style + +Python uses Python-style doc comments. + +For example: + +```py +def swap(x, y): + """ + A function that swaps the values of two variables. + """ + return y, x +``` + +- The documentation are written within a "dead" long string at the start of the function body. +- The parameters cannot be documented with special syntax. +- The documentation are written in Markdown format. + += Issue 1: The syntax of the content of docstrings + +In previous discussion, Markdown Syntax and Typst Syntax are taken into considerations. laurmaedje and people all believes that docstrings should use Typst syntax. + +== Issue 1.1: docstrings with compile errors + +While a docstring has compile errors, it SHOULD be tolerated when rendering the docstring. Two main reasons can cause "sensible" undefined references: +- processor-specific definitions: _Docstring processors_ can add unique definitions to the scope of a docstring. For example, `example` function is defined by tidy, however, it can be not defined by the official docstring processor. +- definitions in the package to render examples: A common case is that developer would like to create examples with the current definitions provided by the package. However, a definition may be invalid when the developer is editing the code. It is not good if docstrings are not rendered during editing. +- backward compatibility issue: people may use an older version of some _docstring processor_ and definitions are not provided in the older version. + +The above example indicates that, only a subset of typst syntax is suggested to be used in docstrings, to allow rendering and parsing with compile errors. + +== Issue 1.2: Compile docstrings with external defintions + +In Issue 1.1, we mentioned that _Docstring processors_ and developers can add definitions to the scope of a docstring. The definitions from the documented package is particularly concerned. We can catergorize the definitions by their visibility: + +- Definitions provided by other packages: the definitions defined by the entry file of a package. +- Definitions provided by other files in the same workspace: the definitions from other files in the same workspace. +- Definitions provided by the current files: the public definitions defined in the current file. In particular, a docstring may access the successor public definitions while is not yet defined while processing the docstring. In particular, a definition can be gone temporarily if a developer is editing the code. +- Private definitions: some definitions may be used or documented, while they are not public or re-exported. for example: + + ````typ + #let new() = { + /// Configures the package. + /// ```example + /// configure() + /// ``` + let configure() = todo() + /// Runs the package. + /// ```example + /// configure() + /// run() + /// ``` + let run() = todo() + + return r( + configure: configure, + run: run, + )un + } + #let pkg = new() + ```` + +== Issue 1.3: Compile docstrings with processor-specific show rules + +Docstring processors may define special show rules to render docstrings. For example, tidy 0.3.0 defines a show rule to render examples: + +```typ +#show raw.where(lang: "exmaple"): render-example +``` + +A docstring processor SHOULD not introduce a show rule if some docstring cannot be rendered without the show rule. + +== Issue 2: The syntax of doc comments + +The python-style is not suitable for Typst, so we may only consider putting documentation in comments. However, it is not yet decided how doc comments should be written. + +=== Issue 2.1: block comments + +Rust doesn't allow block comments as doc comments. It is also not suitable for Typst. At least the `*` prefix used by js-doc style is a valid prefix for block comments. + +=== Issue 2.2: The place of doc comments + +Rust strictly enforces the placement of doc comments. The "Other Expressions" are not allowed to have doc comments. Doc comments of rust CANNOT be placed in a parameter list. + +=== Issue 2.3: Module-level doc comments + +Rust prefixes module-level doc comments with `//!`. The syntax of module-level doc comments should consider other plain comments at the start of the file. + +- shebang: `#!`. Luckily, it is not a valid comment in Typst. +- commented code: A package owner may commented out some code and they may be identified as a module-level doc comment. +- license: A package owner may would like to add a license at the start of the file and before the module-level doc comments. For example: + ```typ + // SPDX-License-Identifier: MIT + /// The file itself is documented by the first line of the file. + ``` + The package owner may not expect the license to be rendered in the documentation. + += Existing Design + +#link("https://myriad-dreamin.github.io/tinymist/feature/docs.html")[tinymist.] + +- A doc comment can be started with either `///` or `//` and the comments with same prefix are grouped together as a a single docstring. This is a loosed syntax because of Issue 2: the syntax of doc comments is not yet decided. +- The docstring is in typst syntax and a docstring can only access the public definitions provided by the current package, if it is in a package. +- The valid places are limited to only before "Let bindings" and at the start of the "Modules" (Files), to ensure simple migration to official syntax in future. + += Unresolved questions + +All of above issues are unresolved questions. From 36525fcbeb14ffccadb3f42c1f7f5226d6b505d0 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 03:01:55 +0800 Subject: [PATCH 02/22] Fix typo in docstring example --- rfcs/0001-doctring-syntax.md | 2 +- rfcs/0001-doctring-syntax.typ | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0001-doctring-syntax.md b/rfcs/0001-doctring-syntax.md index ee461e2..789834a 100644 --- a/rfcs/0001-doctring-syntax.md +++ b/rfcs/0001-doctring-syntax.md @@ -179,7 +179,7 @@ In Issue 1.1, we mentioned that _Docstring processors_ and developers can add de Docstring processors may define special show rules to render docstrings. For example, tidy 0.3.0 defines a show rule to render examples: ```typ -#show raw.where(lang: "exmaple"): render-example +#show raw.where(lang: "example"): render-example ``` A docstring processor SHOULD not introduce a show rule if some docstring cannot be rendered without the show rule. diff --git a/rfcs/0001-doctring-syntax.typ b/rfcs/0001-doctring-syntax.typ index 60f19ac..14196a4 100644 --- a/rfcs/0001-doctring-syntax.typ +++ b/rfcs/0001-doctring-syntax.typ @@ -184,7 +184,7 @@ In Issue 1.1, we mentioned that _Docstring processors_ and developers can add de Docstring processors may define special show rules to render docstrings. For example, tidy 0.3.0 defines a show rule to render examples: ```typ -#show raw.where(lang: "exmaple"): render-example +#show raw.where(lang: "example"): render-example ``` A docstring processor SHOULD not introduce a show rule if some docstring cannot be rendered without the show rule. From 76610795168291f9301eab6dfbc7ac89cb90dece Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 03:07:05 +0800 Subject: [PATCH 03/22] clarify the role of docstring processors --- rfcs/0001-doctring-syntax.typ | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0001-doctring-syntax.typ b/rfcs/0001-doctring-syntax.typ index 14196a4..9fc8681 100644 --- a/rfcs/0001-doctring-syntax.typ +++ b/rfcs/0001-doctring-syntax.typ @@ -56,9 +56,9 @@ This section lists the possible language items that can be documented. Until typ #show: it => it ``` -== The reader of docstrings += Docstring processors -The reader of docstrings are the _docstring processors_. +_docstring processors_ parses, checks, and renders docstrings: - documentation tools, like `tidy`. - analyzers and test frameworks, like `typst-ide`, `tinymist`, and `tytanic`. From 025987456570aebf8cedf754ff2e9a706b70e676 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 03:08:36 +0800 Subject: [PATCH 04/22] Fix grammar errors and update description about compile errors --- rfcs/0001-doctring-syntax.typ | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0001-doctring-syntax.typ b/rfcs/0001-doctring-syntax.typ index 9fc8681..cbefeab 100644 --- a/rfcs/0001-doctring-syntax.typ +++ b/rfcs/0001-doctring-syntax.typ @@ -141,7 +141,7 @@ In previous discussion, Markdown Syntax and Typst Syntax are taken into consider == Issue 1.1: docstrings with compile errors -While a docstring has compile errors, it SHOULD be tolerated when rendering the docstring. Two main reasons can cause "sensible" undefined references: +While a docstring has compile errors, they SHOULD be tolerated when rendering the docstring. The typicial errors SHOULD be ignored are undefined references. There are three main reasons can cause "sensible" undefined references: - processor-specific definitions: _Docstring processors_ can add unique definitions to the scope of a docstring. For example, `example` function is defined by tidy, however, it can be not defined by the official docstring processor. - definitions in the package to render examples: A common case is that developer would like to create examples with the current definitions provided by the package. However, a definition may be invalid when the developer is editing the code. It is not good if docstrings are not rendered during editing. - backward compatibility issue: people may use an older version of some _docstring processor_ and definitions are not provided in the older version. From 223d13c9fb6581d60131d6c854807fbcaf4f1c82 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 03:10:08 +0800 Subject: [PATCH 05/22] Define sources of defintions causing undefined references --- rfcs/0001-doctring-syntax.typ | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0001-doctring-syntax.typ b/rfcs/0001-doctring-syntax.typ index cbefeab..7de01af 100644 --- a/rfcs/0001-doctring-syntax.typ +++ b/rfcs/0001-doctring-syntax.typ @@ -142,8 +142,8 @@ In previous discussion, Markdown Syntax and Typst Syntax are taken into consider == Issue 1.1: docstrings with compile errors While a docstring has compile errors, they SHOULD be tolerated when rendering the docstring. The typicial errors SHOULD be ignored are undefined references. There are three main reasons can cause "sensible" undefined references: -- processor-specific definitions: _Docstring processors_ can add unique definitions to the scope of a docstring. For example, `example` function is defined by tidy, however, it can be not defined by the official docstring processor. -- definitions in the package to render examples: A common case is that developer would like to create examples with the current definitions provided by the package. However, a definition may be invalid when the developer is editing the code. It is not good if docstrings are not rendered during editing. +- undefined processor-specific definitions: _Docstring processors_ can add unique definitions to the scope of a docstring. For example, `example` function is defined by tidy, however, it can be not defined by the official docstring processor. +- undefined definitions from the user modules: A common case is that developer would like to create examples with the current definitions provided by the package. However, a definition may be invalid when the developer is editing the code. It is not good if docstrings are not rendered during editing. - backward compatibility issue: people may use an older version of some _docstring processor_ and definitions are not provided in the older version. The above example indicates that, only a subset of typst syntax is suggested to be used in docstrings, to allow rendering and parsing with compile errors. From 07573633b06bb0bfb113558532efa4252d0cba32 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 03:12:57 +0800 Subject: [PATCH 06/22] Fix descriptions about `*` prefix uses in Typst as special markup --- rfcs/0001-doctring-syntax.typ | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0001-doctring-syntax.typ b/rfcs/0001-doctring-syntax.typ index 7de01af..185d5f3 100644 --- a/rfcs/0001-doctring-syntax.typ +++ b/rfcs/0001-doctring-syntax.typ @@ -195,7 +195,7 @@ The python-style is not suitable for Typst, so we may only consider putting docu === Issue 2.1: block comments -Rust doesn't allow block comments as doc comments. It is also not suitable for Typst. At least the `*` prefix used by js-doc style is a valid prefix for block comments. +Rust doesn't allow block comments as doc comments. It is also not suitable for Typst. At least the `*` prefix used by js-doc style is a special markup in typst. === Issue 2.2: The place of doc comments From 8dcb6873d8eae74147bf1072c601fc299d230268 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 03:13:22 +0800 Subject: [PATCH 07/22] Compile md --- rfcs/0001-doctring-syntax.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/rfcs/0001-doctring-syntax.md b/rfcs/0001-doctring-syntax.md index 789834a..f08bc72 100644 --- a/rfcs/0001-doctring-syntax.md +++ b/rfcs/0001-doctring-syntax.md @@ -50,9 +50,9 @@ This section lists the possible language items that can be documented. Until typ #show: it => it ``` -### The reader of docstrings +## Docstring processors -The reader of docstrings are the _docstring processors_. +_docstring processors_ parses, checks, and renders docstrings: - documentation tools, like `tidy`. - analyzers and test frameworks, like `typst-ide`, `tinymist`, and `tytanic`. @@ -136,10 +136,10 @@ In previous discussion, Markdown Syntax and Typst Syntax are taken into consider ### Issue 1.1: docstrings with compile errors -While a docstring has compile errors, it SHOULD be tolerated when rendering the docstring. Two main reasons can cause "sensible" undefined references: +While a docstring has compile errors, they SHOULD be tolerated when rendering the docstring. The typicial errors SHOULD be ignored are undefined references. There are three main reasons can cause "sensible" undefined references: -- processor-specific definitions: _Docstring processors_ can add unique definitions to the scope of a docstring. For example, `example` function is defined by tidy, however, it can be not defined by the official docstring processor. -- definitions in the package to render examples: A common case is that developer would like to create examples with the current definitions provided by the package. However, a definition may be invalid when the developer is editing the code. It is not good if docstrings are not rendered during editing. +- undefined processor-specific definitions: _Docstring processors_ can add unique definitions to the scope of a docstring. For example, `example` function is defined by tidy, however, it can be not defined by the official docstring processor. +- undefined definitions from the user modules: A common case is that developer would like to create examples with the current definitions provided by the package. However, a definition may be invalid when the developer is editing the code. It is not good if docstrings are not rendered during editing. - backward compatibility issue: people may use an older version of some _docstring processor_ and definitions are not provided in the older version. The above example indicates that, only a subset of typst syntax is suggested to be used in docstrings, to allow rendering and parsing with compile errors. @@ -190,7 +190,7 @@ The python-style is not suitable for Typst, so we may only consider putting docu #### Issue 2.1: block comments -Rust doesn't allow block comments as doc comments. It is also not suitable for Typst. At least the `*` prefix used by js-doc style is a valid prefix for block comments. +Rust doesn't allow block comments as doc comments. It is also not suitable for Typst. At least the `*` prefix used by js-doc style is a special markup in typst. #### Issue 2.2: The place of doc comments From 464f03b82afcd5b186515af879697d8a46b1215e Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 03:15:48 +0800 Subject: [PATCH 08/22] Edit tinymist's module-level doc comment syntax --- rfcs/0001-doctring-syntax.md | 3 ++- rfcs/0001-doctring-syntax.typ | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/rfcs/0001-doctring-syntax.md b/rfcs/0001-doctring-syntax.md index f08bc72..8f58a6f 100644 --- a/rfcs/0001-doctring-syntax.md +++ b/rfcs/0001-doctring-syntax.md @@ -213,9 +213,10 @@ Rust prefixes module-level doc comments with `//!`. The syntax of module-level d [tinymist.](https://myriad-dreamin.github.io/tinymist/feature/docs.html) -- A doc comment can be started with either `///` or `//` and the comments with same prefix are grouped together as a a single docstring. This is a loosed syntax because of Issue 2: the syntax of doc comments is not yet decided. - The docstring is in typst syntax and a docstring can only access the public definitions provided by the current package, if it is in a package. - The valid places are limited to only before "Let bindings" and at the start of the "Modules" (Files), to ensure simple migration to official syntax in future. + - A doc comment of let bindings can be started with either `///` or `//` and the comments with same prefix are grouped together as a a single docstring. This is a loosed syntax because of Issue 2: the syntax of doc comments is not yet decided. + - A doc comment of modules can only start with `///`, because of Issue 2.3: normal comments can occur at the start of the file to include License information. ## Unresolved questions diff --git a/rfcs/0001-doctring-syntax.typ b/rfcs/0001-doctring-syntax.typ index 185d5f3..76b7bd7 100644 --- a/rfcs/0001-doctring-syntax.typ +++ b/rfcs/0001-doctring-syntax.typ @@ -218,9 +218,10 @@ Rust prefixes module-level doc comments with `//!`. The syntax of module-level d #link("https://myriad-dreamin.github.io/tinymist/feature/docs.html")[tinymist.] -- A doc comment can be started with either `///` or `//` and the comments with same prefix are grouped together as a a single docstring. This is a loosed syntax because of Issue 2: the syntax of doc comments is not yet decided. - The docstring is in typst syntax and a docstring can only access the public definitions provided by the current package, if it is in a package. - The valid places are limited to only before "Let bindings" and at the start of the "Modules" (Files), to ensure simple migration to official syntax in future. + - A doc comment of let bindings can be started with either `///` or `//` and the comments with same prefix are grouped together as a a single docstring. This is a loosed syntax because of Issue 2: the syntax of doc comments is not yet decided. + - A doc comment of modules can only start with `///`, because of Issue 2.3: normal comments can occur at the start of the file to include License information. = Unresolved questions From 6c698d6ae834678a5ada14af52958a31475662f0 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 08:04:54 +0800 Subject: [PATCH 09/22] Rename files --- rfcs/{0001-doctring-syntax.md => 0006-doctring-syntax.md} | 0 rfcs/{0001-doctring-syntax.typ => 0006-doctring-syntax.typ} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename rfcs/{0001-doctring-syntax.md => 0006-doctring-syntax.md} (100%) rename rfcs/{0001-doctring-syntax.typ => 0006-doctring-syntax.typ} (100%) diff --git a/rfcs/0001-doctring-syntax.md b/rfcs/0006-doctring-syntax.md similarity index 100% rename from rfcs/0001-doctring-syntax.md rename to rfcs/0006-doctring-syntax.md diff --git a/rfcs/0001-doctring-syntax.typ b/rfcs/0006-doctring-syntax.typ similarity index 100% rename from rfcs/0001-doctring-syntax.typ rename to rfcs/0006-doctring-syntax.typ From 1789e0f3ee54bd8c161f6e96492d5cb3c5987115 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:05:21 +0800 Subject: [PATCH 10/22] Refine docstring syntax RFC with clearer language and examples --- rfcs/0006-doctring-syntax.md | 311 +++++++++++++++++++++++++++++++--- rfcs/0006-doctring-syntax.typ | 300 +++++++++++++++++++++++++++++--- 2 files changed, 559 insertions(+), 52 deletions(-) diff --git a/rfcs/0006-doctring-syntax.md b/rfcs/0006-doctring-syntax.md index 8f58a6f..f0bc198 100644 --- a/rfcs/0006-doctring-syntax.md +++ b/rfcs/0006-doctring-syntax.md @@ -9,7 +9,7 @@ This RFC discusses the syntax for docstrings in Typst. A docstring is an item in ## Motivation -People need to be able to write documentation over language items for their packages. +People SHOULD have the capability to write documentation about language items. ## The language items that can be documented @@ -50,6 +50,16 @@ This section lists the possible language items that can be documented. Until typ #show: it => it ``` +- Expression Operands. For example, the `a` in the following example. + ```typ + #let condition = ( + /// `a` must be greater than `b`. + a > b and + /// `a` must be less than `c`. + a < c + ) + ``` + ## Docstring processors _docstring processors_ parses, checks, and renders docstrings: @@ -59,13 +69,11 @@ _docstring processors_ parses, checks, and renders docstrings: ## Existing docstring styles -This section lists the existing docstring styles. Languages put documentation in comments or real strings in specific locations. The comments holding the documentation are usually called doc comments. - -### JsDoc-style +This section lists the existing docstring styles. Languages identify comments or strings in specific locations as docstrings, and hold the documentation in them. The comments holding the documentation are usually called doc comments. -Javscript and Typescript use JsDoc-style docstrings. +### JsDoc style -For example: +Javscript and Typescript use JsDoc. For example: ```js /** @@ -85,11 +93,9 @@ function swap(x, y) { - The annotations are written within `@param` and `@returns` tags. - The documentation are written in Markdown format. -### Rust-style +### Rust style -Rust uses Rust-style docstrings. - -For example: +Rust documents code with doc comments. For example: ```rs /// A function that swaps the values of two variables. @@ -112,11 +118,24 @@ fn swap(x: i32, y: i32) -> (i32, i32) { - The parameters cannot be documented with special syntax. - The documentation are written in Markdown format. -### Python-style +Besides, Rust allows to add documentation by macros. For example: + +```rs +#[doc = "A function that swaps the values of two variables."] +fn swap(x: i32, y: i32) -> (i32, i32) { + (y, x) +} +``` + +Rust also allows to include README.md as a module-level docstring. + +```rs +#![doc = include_str!("README.md")] +``` -Python uses Python-style doc comments. +### Python style -For example: +Python documents code within a long string. For example: ```py def swap(x, y): @@ -132,7 +151,7 @@ def swap(x, y): ## Issue 1: The syntax of the content of docstrings -In previous discussion, Markdown Syntax and Typst Syntax are taken into considerations. laurmaedje and people all believes that docstrings should use Typst syntax. +In previous discussion, Markdown Syntax and Typst Syntax are taken into considerations. official typst and people all believe that docstrings should use Typst syntax. ### Issue 1.1: docstrings with compile errors @@ -142,7 +161,7 @@ While a docstring has compile errors, they SHOULD be tolerated when rendering th - undefined definitions from the user modules: A common case is that developer would like to create examples with the current definitions provided by the package. However, a definition may be invalid when the developer is editing the code. It is not good if docstrings are not rendered during editing. - backward compatibility issue: people may use an older version of some _docstring processor_ and definitions are not provided in the older version. -The above example indicates that, only a subset of typst syntax is suggested to be used in docstrings, to allow rendering and parsing with compile errors. +The above example indicates that only a subset of typst syntax is suggested to be used in docstrings, to allow rendering and parsing with compile errors. ### Issue 1.2: Compile docstrings with external defintions @@ -182,21 +201,69 @@ Docstring processors may define special show rules to render docstrings. For exa #show raw.where(lang: "example"): render-example ``` -A docstring processor SHOULD not introduce a show rule if some docstring cannot be rendered without the show rule. +### Issue 1.4: CJK issue + +If the newline is preserved in the docstring, the CJK characters may be rendered with a unwanted space. + +```typ +/// 你好， +/// 世界 +#let id(x) = x +``` + +The content of the above docstring may be "你好n世界" (Unicode `U+4F60 U+597D U+FF0C U+0A U+4E16 U+754C`) and rendered as "你好， 世界" (Unicode `U+4F60 U+597D U+FF0C U+20 U+4E16 U+754C`). ### Issue 2: The syntax of doc comments -The python-style is not suitable for Typst, so we may only consider putting documentation in comments. However, it is not yet decided how doc comments should be written. +The python style is not suitable for Typst, because typst doesn't discard values in python's way. We may only consider putting documentation in comments, either following JsDoc or Rust style. It is not yet decided how doc comments should be written. + +#### Issue 2.1: block comments (JsDoc style) + +Rust style doesn't allow block comments as doc comments. It is also not suitable for Typst. At least the `*` prefix used by js-doc style is a special markup in typst. + +#### Issue 2.2: prefix line comments or not (Two slashes v.s. three slashes) -#### Issue 2.1: block comments +Rust style prefixes doc comments with three slashes, but official typst hesitates to introduce such syntax for doc comments, considering adding complexity to people who are not familiar with programming languages. Previous discussion shows that many participants also dislike recognize two-slash line comments as doc comments, because the commented code may be occasionally recognized as a doc comment. -Rust doesn't allow block comments as doc comments. It is also not suitable for Typst. At least the `*` prefix used by js-doc style is a special markup in typst. +Rust style also allows to prefix line comments with a `!` (Unicode `U+0021`). Typst style may not follow that considering the point raised by the discussion mentioned above. + +#### Issue 2.3: The place of doc comments + +Rust strictly enforces the placement of doc comments. + +"Other Expressions" in Rust are not allowed to have doc comments. rustfmt also hates comments in many weird places, especially comments between expression operands, and refuses to format code with weird comment positions. + +Existing docstring processors have different opinions on the placement documentation for "Parameters". tidy v0.4.0 places documentation for "Parameters" inside the parameter list. For example: + +```typ +#let swap( + /// The first variable to swap. + x, + /// The second variable to swap. + y, +) = (y, x) +``` -#### Issue 2.2: The place of doc comments +tinymist doesn't follow that, with three points: -Rust strictly enforces the placement of doc comments. The "Other Expressions" are not allowed to have doc comments. Doc comments of rust CANNOT be placed in a parameter list. +- It is unfriendly for typst formatters to process comments like that. +- Official typst may not allow to add documentation inside the parameter list, and tinymist will follow official typst. +- New syntax makes it hard to recognize in-place parameter destruction. For example: + ```typ + #let exchange(( + /// The first variable to exchange. + x, + ( + /// The second variable to exchange. + y, + /// The third variable to exchange. + z, + ) + )) = ((x, y), z) + ``` + Some people argues that, in-place parameter destructing in API functions is considered. -#### Issue 2.3: Module-level doc comments +#### Issue 2.4: Module-level doc comments Rust prefixes module-level doc comments with `//!`. The syntax of module-level doc comments should consider other plain comments at the start of the file. @@ -209,15 +276,207 @@ Rust prefixes module-level doc comments with `//!`. The syntax of module-level d ``` The package owner may not expect the license to be rendered in the documentation. -## Existing Design +## Existing Design: tinymist and tidy v0.3.0 -[tinymist.](https://myriad-dreamin.github.io/tinymist/feature/docs.html) +See [tinymist](https://myriad-dreamin.github.io/tinymist/feature/docs.html) and [tidy.](https://typst.app/universe/package/tidy) - The docstring is in typst syntax and a docstring can only access the public definitions provided by the current package, if it is in a package. - The valid places are limited to only before "Let bindings" and at the start of the "Modules" (Files), to ensure simple migration to official syntax in future. - A doc comment of let bindings can be started with either `///` or `//` and the comments with same prefix are grouped together as a a single docstring. This is a loosed syntax because of Issue 2: the syntax of doc comments is not yet decided. - A doc comment of modules can only start with `///`, because of Issue 2.3: normal comments can occur at the start of the file to include License information. -## Unresolved questions +## Proposed Design + +### Valid places + +Definite places: + +- Before "Let bindings" +- At the start of the "Modules" (Files) + +Definite places in future: + +- "Custom Types" and their "Fields": + ```typ + /// A point in 2D space whose axes coordinate values are of type `T`. + #type Point(T) = { + /// The x-axis coordinate of the point. + field x: T + /// The y-axis coordinate of the point. + field y: T + } + ``` + +Possible places and suggested by this RFC: + +- Exactly before "Parameters" or "Destructed variables". This is because the parameter list in typst are usually very long. + +Possible places and not suggested by this RFC: + +- "Other Expressions" + +### Syntax of doc comments + +Only introduce `///` as the syntax of doc comments. + +Despite adding complexity, not introducing new syntax has two disadvantages: + +- P1: it is not friendly to add license information when we also want to add a module-level docstring. +- When commenting out code, the commented code may be occasionally recognized as a doc comment or cause failing compilation of the related docstring. + +Despite adding complexity, it doesn't add much: + +- regular users don't have to learn if they are not going to document code. +- the introduced syntax is relatively easy and it is easy to learn and discover. When one want to add documentation, they can soonly find the syntax in the official documentation by the keyword `docstring` or `documentation`. Tutorial can also mention the syntax in short, because it is simple. + +The consecutive doc comments are grouped as a single docstring, and the docstring only documents adjacent "Modules" and "Let bindings". The `/` prefix are removed when parsing the docstring and common indents are removed (dedented) when rendering the docstring. + +The Example 1 to 5 all have content "Hello World.": + +Example 1 (documenting `id`): + +```typ +/// Hello World. +#let id(x) = x +``` + +Example 2 (documenting `id`): + +```typ +/// Hello +/// World. +#let id(x) = x +``` + +Example 3 (documenting `id`): + +```typ +// Random comment. +/// Hello +/// World. +#let id(x) = x +``` + +Example 4 (documenting the file itself): + +```typ +#!/usr/bin/env typst +/// Hello +/// World. + +/// Hello World. +#let id(x) = x +``` + +Example 5 (documenting the file itself): + +```typ +#!/usr/bin/env typst +// SPDX-License-Identifier: MIT +/// Hello +/// World. +``` + +The Example 6 to 8 are all document nothing (incorrect places). + +Example 6 (not at the start of the file): + +```typ +#!/usr/bin/env typst + +/// Hello +/// World. +``` + +Example 7 (not exactly before "Let bindings"): + +```typ +#!/usr/bin/env typst + +/// Hello +/// World. + +#let id(x) = x +``` + +Example 8 (not exactly before "Let bindings"): + +```typ +#!/usr/bin/env typst + +/// Hello +/// World. +// Random comment. +#let id(x) = x +``` + +### Evaluating the content of docstrings + +The content is in Typst syntax. By default, no new definitions can be used in the content of docstrings. + +In `typst.toml`, a `docs.prelude` is used to introduce definitions to the content of docstrings. For example: + +```toml +[docs] +prelude = "@preview/tidy:0.4.0" +``` + +And the tidy v0.4.0 package will contain the metadata to help evaluate the content of docstrings. + +The computed prelude is directly prepended to the content of docstrings. For example, if `tidy` tells the prelude is `#let example(it) = it.text;` and the content of docstring is `#example[Example]`, the docstring will be compiled with content `#let example(it) = it.text; #example[Example]` and rendered as `Example`. + +Sample prelude implementation: + +```typ +#let tidy-version = version(sys.inputs.tidy-host-version) +#let example(it) = it.text +#show: it => { + show ref: it => { + if tidy-version >= version(0, 4, 0) { + tidy-render-reference(it) // Provided by tidy or tinymist processor + } else { + it + } + } + + it +} +``` + +Sample docstring processor implementation that implements the `tidy-render-reference` function and extracts the base docs and parameter docs: + +```rs +let scope = Scope::new(); +scope.define::(); +let inputs = typst::dict! { tidy-version: "0.4.0" }; +let document: typst::html::HtmlDocument = compile_with_scope(content, &scope, &inputs)?; +let base_docs = convert_to_markdown(document.html()?); +let parameter_docs = typst::query(document, "")?.map(convert_to_markdown); +return Docstring { + base_docs, + parameter_docs, +} +``` + +## Discussion: Backward compatibility of syntax + +The docstrings are evaluated based on the prelude defined by official typst (default prelude) and the used docstring processor (custom prelude). + +Two main factors can affect the backward compatibility: + +- The typst version to render the docstring. +- The docstring processor used to process the docstring. + +Since the prelude is defined in `typst.toml`, a minimal typst version can be specified, which determines the default prelude and compiler to render the docstring. Besides `min-version`, A `typst-version` is suggested to added to `typst.toml` to tell which typst version ensures to render the typst syntax used by docstring. + +## Discussion: Customizing the docstring handlers + +_Docstring processors_ can add show rules to customize the docstring rendering. In the sample prelude implementation, the prelude can do nothing if the host doesn't implement a tidy defined docs interfaces and the parameter docs are left in the "base docs" and shown to the users. + +## Discussion: Error tolerance + +As discussed in Issue 1.1, the docstrings SHOULD have syntax that can be extracted partial content even if there are compile errors, which improves editing and developer experience. However, this is optional, and may be discussed in future, because "Backward compatibility of syntax" ensures that when the code has correct syntax, the docstring can be rendered determinsitically with backward compatibility. + +## Discussion: Multiple-lingual docstrings and internationalization -All of above issues are unresolved questions. +Left as an unresolved question. diff --git a/rfcs/0006-doctring-syntax.typ b/rfcs/0006-doctring-syntax.typ index 76b7bd7..85e9b81 100644 --- a/rfcs/0006-doctring-syntax.typ +++ b/rfcs/0006-doctring-syntax.typ @@ -10,7 +10,7 @@ This RFC discusses the syntax for docstrings in Typst. A docstring is an item in = Motivation -People need to be able to write documentation over language items for their packages. +People SHOULD have the capability to write documentation about language items. = The language items that can be documented @@ -56,6 +56,17 @@ This section lists the possible language items that can be documented. Until typ #show: it => it ``` +- Expression Operands. For example, the `a` in the following example. + + ```typ + #let condition = ( + /// `a` must be greater than `b`. + a > b and + /// `a` must be less than `c`. + a < c + ) + ``` + = Docstring processors _docstring processors_ parses, checks, and renders docstrings: @@ -64,13 +75,11 @@ _docstring processors_ parses, checks, and renders docstrings: = Existing docstring styles -This section lists the existing docstring styles. Languages put documentation in comments or real strings in specific locations. The comments holding the documentation are usually called doc comments. +This section lists the existing docstring styles. Languages identify comments or strings in specific locations as docstrings, and hold the documentation in them. The comments holding the documentation are usually called doc comments. -== JsDoc-style +== JsDoc style -Javscript and Typescript use JsDoc-style docstrings. - -For example: +Javscript and Typescript use JsDoc. For example: ```js /** @@ -90,11 +99,9 @@ function swap(x, y) { - The annotations are written within `@param` and `@returns` tags. - The documentation are written in Markdown format. -== Rust-style - -Rust uses Rust-style docstrings. +== Rust style -For example: +Rust documents code with doc comments. For example: ```rs /// A function that swaps the values of two variables. @@ -117,11 +124,24 @@ fn swap(x: i32, y: i32) -> (i32, i32) { - The parameters cannot be documented with special syntax. - The documentation are written in Markdown format. -== Python-style +Besides, Rust allows to add documentation by macros. For example: + +```rs +#[doc = "A function that swaps the values of two variables."] +fn swap(x: i32, y: i32) -> (i32, i32) { + (y, x) +} +``` -Python uses Python-style doc comments. +Rust also allows to include README.md as a module-level docstring. -For example: +```rs +#![doc = include_str!("README.md")] +``` + +== Python style + +Python documents code within a long string. For example: ```py def swap(x, y): @@ -137,7 +157,7 @@ def swap(x, y): = Issue 1: The syntax of the content of docstrings -In previous discussion, Markdown Syntax and Typst Syntax are taken into considerations. laurmaedje and people all believes that docstrings should use Typst syntax. +In previous discussion, Markdown Syntax and Typst Syntax are taken into considerations. official typst and people all believe that docstrings should use Typst syntax. == Issue 1.1: docstrings with compile errors @@ -146,7 +166,7 @@ While a docstring has compile errors, they SHOULD be tolerated when rendering th - undefined definitions from the user modules: A common case is that developer would like to create examples with the current definitions provided by the package. However, a definition may be invalid when the developer is editing the code. It is not good if docstrings are not rendered during editing. - backward compatibility issue: people may use an older version of some _docstring processor_ and definitions are not provided in the older version. -The above example indicates that, only a subset of typst syntax is suggested to be used in docstrings, to allow rendering and parsing with compile errors. +The above example indicates that only a subset of typst syntax is suggested to be used in docstrings, to allow rendering and parsing with compile errors. == Issue 1.2: Compile docstrings with external defintions @@ -187,21 +207,69 @@ Docstring processors may define special show rules to render docstrings. For exa #show raw.where(lang: "example"): render-example ``` -A docstring processor SHOULD not introduce a show rule if some docstring cannot be rendered without the show rule. +== Issue 1.4: CJK issue + +If the newline is preserved in the docstring, the CJK characters may be rendered with a unwanted space. + +```typ +/// 你好， +/// 世界 +#let id(x) = x +``` + +The content of the above docstring may be "你好\n世界" (Unicode `U+4F60 U+597D U+FF0C U+0A U+4E16 U+754C`) and rendered as "你好， 世界" (Unicode `U+4F60 U+597D U+FF0C U+20 U+4E16 U+754C`). == Issue 2: The syntax of doc comments -The python-style is not suitable for Typst, so we may only consider putting documentation in comments. However, it is not yet decided how doc comments should be written. +The python style is not suitable for Typst, because typst doesn't discard values in python's way. We may only consider putting documentation in comments, either following JsDoc or Rust style. It is not yet decided how doc comments should be written. + +=== Issue 2.1: block comments (JsDoc style) + +Rust style doesn't allow block comments as doc comments. It is also not suitable for Typst. At least the `*` prefix used by js-doc style is a special markup in typst. + +=== Issue 2.2: prefix line comments or not (Two slashes v.s. three slashes) + +Rust style prefixes doc comments with three slashes, but official typst hesitates to introduce such syntax for doc comments, considering adding complexity to people who are not familiar with programming languages. Previous discussion shows that many participants also dislike recognize two-slash line comments as doc comments, because the commented code may be occasionally recognized as a doc comment. + +Rust style also allows to prefix line comments with a `!` (Unicode `U+0021`). Typst style may not follow that considering the point raised by the discussion mentioned above. + +=== Issue 2.3: The place of doc comments -=== Issue 2.1: block comments +Rust strictly enforces the placement of doc comments. -Rust doesn't allow block comments as doc comments. It is also not suitable for Typst. At least the `*` prefix used by js-doc style is a special markup in typst. +"Other Expressions" in Rust are not allowed to have doc comments. rustfmt also hates comments in many weird places, especially comments between expression operands, and refuses to format code with weird comment positions. -=== Issue 2.2: The place of doc comments +Existing docstring processors have different opinions on the placement documentation for "Parameters". tidy v0.4.0 places documentation for "Parameters" inside the parameter list. For example: -Rust strictly enforces the placement of doc comments. The "Other Expressions" are not allowed to have doc comments. Doc comments of rust CANNOT be placed in a parameter list. +```typ +#let swap( + /// The first variable to swap. + x, + /// The second variable to swap. + y, +) = (y, x) +``` -=== Issue 2.3: Module-level doc comments +tinymist doesn't follow that, with three points: +- It is unfriendly for typst formatters to process comments like that. +- Official typst may not allow to add documentation inside the parameter list, and tinymist will follow official typst. +- New syntax makes it hard to recognize in-place parameter destruction. For example: + ```typ + #let exchange(( + /// The first variable to exchange. + x, + ( + /// The second variable to exchange. + y, + /// The third variable to exchange. + z, + ) + )) = ((x, y), z) + ``` + + Some people argues that, in-place parameter destructing in API functions is considered. + +=== Issue 2.4: Module-level doc comments Rust prefixes module-level doc comments with `//!`. The syntax of module-level doc comments should consider other plain comments at the start of the file. @@ -214,15 +282,195 @@ Rust prefixes module-level doc comments with `//!`. The syntax of module-level d ``` The package owner may not expect the license to be rendered in the documentation. -= Existing Design += Existing Design: tinymist and tidy v0.3.0 -#link("https://myriad-dreamin.github.io/tinymist/feature/docs.html")[tinymist.] +See #link("https://myriad-dreamin.github.io/tinymist/feature/docs.html")[tinymist ] and #link("https://typst.app/universe/package/tidy")[tidy.] - The docstring is in typst syntax and a docstring can only access the public definitions provided by the current package, if it is in a package. - The valid places are limited to only before "Let bindings" and at the start of the "Modules" (Files), to ensure simple migration to official syntax in future. - A doc comment of let bindings can be started with either `///` or `//` and the comments with same prefix are grouped together as a a single docstring. This is a loosed syntax because of Issue 2: the syntax of doc comments is not yet decided. - A doc comment of modules can only start with `///`, because of Issue 2.3: normal comments can occur at the start of the file to include License information. -= Unresolved questions += Proposed Design + +== Valid places + +Definite places: + +- Before "Let bindings" +- At the start of the "Modules" (Files) + +Definite places in future: +- "Custom Types" and their "Fields": + ```typ + /// A point in 2D space whose axes coordinate values are of type `T`. + #type Point(T) = { + /// The x-axis coordinate of the point. + field x: T + /// The y-axis coordinate of the point. + field y: T + } + ``` + +Possible places and suggested by this RFC: + +- Exactly before "Parameters" or "Destructed variables". This is because the parameter list in typst are usually very long. + +Possible places and not suggested by this RFC: + +- "Other Expressions" + +== Syntax of doc comments + +Only introduce `///` as the syntax of doc comments. + +Despite adding complexity, not introducing new syntax has two disadvantages: +- P1: it is not friendly to add license information when we also want to add a module-level docstring. +- When commenting out code, the commented code may be occasionally recognized as a doc comment or cause failing compilation of the related docstring. +Despite adding complexity, it doesn't add much: +- regular users don't have to learn if they are not going to document code. +- the introduced syntax is relatively easy and it is easy to learn and discover. When one want to add documentation, they can soonly find the syntax in the official documentation by the keyword `docstring` or `documentation`. Tutorial can also mention the syntax in short, because it is simple. + +The consecutive doc comments are grouped as a single docstring, and the docstring only documents adjacent "Modules" and "Let bindings". The `/` prefix are removed when parsing the docstring and common indents are removed (dedented) when rendering the docstring. + +The Example 1 to 5 all have content "Hello World.": + +Example 1 (documenting `id`): + +```typ +/// Hello World. +#let id(x) = x +``` + +Example 2 (documenting `id`): +```typ +/// Hello +/// World. +#let id(x) = x +``` + +Example 3 (documenting `id`): +```typ +// Random comment. +/// Hello +/// World. +#let id(x) = x +``` + +Example 4 (documenting the file itself): +```typ +#!/usr/bin/env typst +/// Hello +/// World. + +/// Hello World. +#let id(x) = x +``` + +Example 5 (documenting the file itself): +```typ +#!/usr/bin/env typst +// SPDX-License-Identifier: MIT +/// Hello +/// World. +``` + +The Example 6 to 8 are all document nothing (incorrect places). + +Example 6 (not at the start of the file): +```typ +#!/usr/bin/env typst + +/// Hello +/// World. +``` + +Example 7 (not exactly before "Let bindings"): +```typ +#!/usr/bin/env typst + +/// Hello +/// World. + +#let id(x) = x +``` + +Example 8 (not exactly before "Let bindings"): +```typ +#!/usr/bin/env typst + +/// Hello +/// World. +// Random comment. +#let id(x) = x +``` + +== Evaluating the content of docstrings + +The content is in Typst syntax. By default, no new definitions can be used in the content of docstrings. + +In `typst.toml`, a `docs.prelude` is used to introduce definitions to the content of docstrings. For example: + +```toml +[docs] +prelude = "@preview/tidy:0.4.0" +``` + +And the tidy v0.4.0 package will contain the metadata to help evaluate the content of docstrings. + +The computed prelude is directly prepended to the content of docstrings. For example, if `tidy` tells the prelude is `#let example(it) = it.text;` and the content of docstring is `#example[Example]`, the docstring will be compiled with content `#let example(it) = it.text; #example[Example]` and rendered as `Example`. + +Sample prelude implementation: + +```typ +#let tidy-version = version(sys.inputs.tidy-host-version) +#let example(it) = it.text +#show: it => { + show ref: it => { + if tidy-version >= version(0, 4, 0) { + tidy-render-reference(it) // Provided by tidy or tinymist processor + } else { + it + } + } + + it +} +``` + +Sample docstring processor implementation that implements the `tidy-render-reference` function and extracts the base docs and parameter docs: + +```rs +let scope = Scope::new(); +scope.define::(); +let inputs = typst::dict! { tidy-version: "0.4.0" }; +let document: typst::html::HtmlDocument = compile_with_scope(content, &scope, &inputs)?; +let base_docs = convert_to_markdown(document.html()?); +let parameter_docs = typst::query(document, "")?.map(convert_to_markdown); +return Docstring { + base_docs, + parameter_docs, +} +``` + += Discussion: Backward compatibility of syntax + +The docstrings are evaluated based on the prelude defined by official typst (default prelude) and the used docstring processor (custom prelude). + +Two main factors can affect the backward compatibility: +- The typst version to render the docstring. +- The docstring processor used to process the docstring. + +Since the prelude is defined in `typst.toml`, a minimal typst version can be specified, which determines the default prelude and compiler to render the docstring. Besides `min-version`, A `typst-version` is suggested to added to `typst.toml` to tell which typst version ensures to render the typst syntax used by docstring. + += Discussion: Customizing the docstring handlers + +_Docstring processors_ can add show rules to customize the docstring rendering. In the sample prelude implementation, the prelude can do nothing if the host doesn't implement a tidy defined docs interfaces and the parameter docs are left in the "base docs" and shown to the users. + += Discussion: Error tolerance + +As discussed in Issue 1.1, the docstrings SHOULD have syntax that can be extracted partial content even if there are compile errors, which improves editing and developer experience. However, this is optional, and may be discussed in future, because "Backward compatibility of syntax" ensures that when the code has correct syntax, the docstring can be rendered determinsitically with backward compatibility. + += Discussion: Multiple-lingual docstrings and internationalization -All of above issues are unresolved questions. +Left as an unresolved question. From d2a338389370d78c25510358212a7527a2c5f78a Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:08:46 +0800 Subject: [PATCH 11/22] Add clarification on the scope of docstring processors in the RFC --- rfcs/0006-doctring-syntax.typ | 2 ++ 1 file changed, 2 insertions(+) diff --git a/rfcs/0006-doctring-syntax.typ b/rfcs/0006-doctring-syntax.typ index 85e9b81..0019816 100644 --- a/rfcs/0006-doctring-syntax.typ +++ b/rfcs/0006-doctring-syntax.typ @@ -467,6 +467,8 @@ Since the prelude is defined in `typst.toml`, a minimal typst version can be spe _Docstring processors_ can add show rules to customize the docstring rendering. In the sample prelude implementation, the prelude can do nothing if the host doesn't implement a tidy defined docs interfaces and the parameter docs are left in the "base docs" and shown to the users. +The best practice or design pattern for _docstring processors_ to customize the docstring handlers is out of the scope of this RFC, which only discusses the syntax of docstrings. + = Discussion: Error tolerance As discussed in Issue 1.1, the docstrings SHOULD have syntax that can be extracted partial content even if there are compile errors, which improves editing and developer experience. However, this is optional, and may be discussed in future, because "Backward compatibility of syntax" ensures that when the code has correct syntax, the docstring can be rendered determinsitically with backward compatibility. From 2b543eed55bf9773e9b29bc1077e946bf227c4b3 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:12:07 +0800 Subject: [PATCH 12/22] Move CJK issue discussion to the 'Discussion' section and clarify newline rendering behavior in docstrings --- rfcs/0006-doctring-syntax.typ | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/rfcs/0006-doctring-syntax.typ b/rfcs/0006-doctring-syntax.typ index 0019816..556ad71 100644 --- a/rfcs/0006-doctring-syntax.typ +++ b/rfcs/0006-doctring-syntax.typ @@ -207,18 +207,6 @@ Docstring processors may define special show rules to render docstrings. For exa #show raw.where(lang: "example"): render-example ``` -== Issue 1.4: CJK issue - -If the newline is preserved in the docstring, the CJK characters may be rendered with a unwanted space. - -```typ -/// 你好， -/// 世界 -#let id(x) = x -``` - -The content of the above docstring may be "你好\n世界" (Unicode `U+4F60 U+597D U+FF0C U+0A U+4E16 U+754C`) and rendered as "你好， 世界" (Unicode `U+4F60 U+597D U+FF0C U+20 U+4E16 U+754C`). - == Issue 2: The syntax of doc comments The python style is not suitable for Typst, because typst doesn't discard values in python's way. We may only consider putting documentation in comments, either following JsDoc or Rust style. It is not yet decided how doc comments should be written. @@ -475,4 +463,14 @@ As discussed in Issue 1.1, the docstrings SHOULD have syntax that can be extract = Discussion: Multiple-lingual docstrings and internationalization +If the newline is preserved in the docstring, the documentation in CJK may be rendered with a unwanted space. + +```typ +/// 你好， +/// 世界 +#let id(x) = x +``` + +The content of the above docstring may be "你好\n世界" (Unicode `U+4F60 U+597D U+FF0C U+0A U+4E16 U+754C`) and rendered as "你好， 世界" (Unicode `U+4F60 U+597D U+FF0C U+20 U+4E16 U+754C`). + Left as an unresolved question. From 99930269cc4a05334a45ba0f802a82a1f1d9ce20 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:14:06 +0800 Subject: [PATCH 13/22] noting unresolved issues --- rfcs/0006-doctring-syntax.typ | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/rfcs/0006-doctring-syntax.typ b/rfcs/0006-doctring-syntax.typ index 556ad71..43aa3e8 100644 --- a/rfcs/0006-doctring-syntax.typ +++ b/rfcs/0006-doctring-syntax.typ @@ -473,4 +473,6 @@ If the newline is preserved in the docstring, the documentation in CJK may be re The content of the above docstring may be "你好\n世界" (Unicode `U+4F60 U+597D U+FF0C U+0A U+4E16 U+754C`) and rendered as "你好， 世界" (Unicode `U+4F60 U+597D U+FF0C U+20 U+4E16 U+754C`). -Left as an unresolved question. +Since a package may target non-programming users and non-English speakers, the internationalization of docstrings is considered a important issue. + +These issues are left as an unresolved in this RFC. From 03c8abb2b181a89f6ef5f12933924af42e2960fa Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:16:33 +0800 Subject: [PATCH 14/22] compile the document --- rfcs/0006-doctring-syntax.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/rfcs/0006-doctring-syntax.md b/rfcs/0006-doctring-syntax.md index f0bc198..063958b 100644 --- a/rfcs/0006-doctring-syntax.md +++ b/rfcs/0006-doctring-syntax.md @@ -201,18 +201,6 @@ Docstring processors may define special show rules to render docstrings. For exa #show raw.where(lang: "example"): render-example ``` -### Issue 1.4: CJK issue - -If the newline is preserved in the docstring, the CJK characters may be rendered with a unwanted space. - -```typ -/// 你好， -/// 世界 -#let id(x) = x -``` - -The content of the above docstring may be "你好n世界" (Unicode `U+4F60 U+597D U+FF0C U+0A U+4E16 U+754C`) and rendered as "你好， 世界" (Unicode `U+4F60 U+597D U+FF0C U+20 U+4E16 U+754C`). - ### Issue 2: The syntax of doc comments The python style is not suitable for Typst, because typst doesn't discard values in python's way. We may only consider putting documentation in comments, either following JsDoc or Rust style. It is not yet decided how doc comments should be written. @@ -473,10 +461,24 @@ Since the prelude is defined in `typst.toml`, a minimal typst version can be spe _Docstring processors_ can add show rules to customize the docstring rendering. In the sample prelude implementation, the prelude can do nothing if the host doesn't implement a tidy defined docs interfaces and the parameter docs are left in the "base docs" and shown to the users. +The best practice or design pattern for _docstring processors_ to customize the docstring handlers is out of the scope of this RFC, which only discusses the syntax of docstrings. + ## Discussion: Error tolerance As discussed in Issue 1.1, the docstrings SHOULD have syntax that can be extracted partial content even if there are compile errors, which improves editing and developer experience. However, this is optional, and may be discussed in future, because "Backward compatibility of syntax" ensures that when the code has correct syntax, the docstring can be rendered determinsitically with backward compatibility. ## Discussion: Multiple-lingual docstrings and internationalization -Left as an unresolved question. +If the newline is preserved in the docstring, the documentation in CJK may be rendered with a unwanted space. + +```typ +/// 你好， +/// 世界 +#let id(x) = x +``` + +The content of the above docstring may be "你好n世界" (Unicode `U+4F60 U+597D U+FF0C U+0A U+4E16 U+754C`) and rendered as "你好， 世界" (Unicode `U+4F60 U+597D U+FF0C U+20 U+4E16 U+754C`). + +Since a package may target non-programming users and non-English speakers, the internationalization of docstrings is considered a important issue. + +These issues are left as an unresolved in this RFC. From d2d7039aa214d57264a606276ffd883e51f8006a Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:20:20 +0800 Subject: [PATCH 15/22] missing "as a bad practice" --- rfcs/0006-doctring-syntax.md | 2 +- rfcs/0006-doctring-syntax.typ | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0006-doctring-syntax.md b/rfcs/0006-doctring-syntax.md index 063958b..f5d8356 100644 --- a/rfcs/0006-doctring-syntax.md +++ b/rfcs/0006-doctring-syntax.md @@ -249,7 +249,7 @@ tinymist doesn't follow that, with three points: ) )) = ((x, y), z) ``` - Some people argues that, in-place parameter destructing in API functions is considered. + Some people argues that, in-place parameter destructing in API functions is considered as a bad practice. #### Issue 2.4: Module-level doc comments diff --git a/rfcs/0006-doctring-syntax.typ b/rfcs/0006-doctring-syntax.typ index 43aa3e8..4a863cd 100644 --- a/rfcs/0006-doctring-syntax.typ +++ b/rfcs/0006-doctring-syntax.typ @@ -255,7 +255,7 @@ tinymist doesn't follow that, with three points: )) = ((x, y), z) ``` - Some people argues that, in-place parameter destructing in API functions is considered. + Some people argues that, in-place parameter destructing in API functions is considered as a bad practice. === Issue 2.4: Module-level doc comments From 562600358c1abf2d29ecffb45e504f0a7af5e26c Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:21:09 +0800 Subject: [PATCH 16/22] Edit shebang syntax comment --- rfcs/0006-doctring-syntax.md | 2 +- rfcs/0006-doctring-syntax.typ | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0006-doctring-syntax.md b/rfcs/0006-doctring-syntax.md index f5d8356..f8fbc33 100644 --- a/rfcs/0006-doctring-syntax.md +++ b/rfcs/0006-doctring-syntax.md @@ -255,7 +255,7 @@ tinymist doesn't follow that, with three points: Rust prefixes module-level doc comments with `//!`. The syntax of module-level doc comments should consider other plain comments at the start of the file. -- shebang: `#!`. Luckily, it is not a valid comment in Typst. +- shebang: `#!`. Luckily, it is not a valid syntax in Typst. - commented code: A package owner may commented out some code and they may be identified as a module-level doc comment. - license: A package owner may would like to add a license at the start of the file and before the module-level doc comments. For example: ```typ diff --git a/rfcs/0006-doctring-syntax.typ b/rfcs/0006-doctring-syntax.typ index 4a863cd..5ba7eca 100644 --- a/rfcs/0006-doctring-syntax.typ +++ b/rfcs/0006-doctring-syntax.typ @@ -261,7 +261,7 @@ tinymist doesn't follow that, with three points: Rust prefixes module-level doc comments with `//!`. The syntax of module-level doc comments should consider other plain comments at the start of the file. -- shebang: `#!`. Luckily, it is not a valid comment in Typst. +- shebang: `#!`. Luckily, it is not a valid syntax in Typst. - commented code: A package owner may commented out some code and they may be identified as a module-level doc comment. - license: A package owner may would like to add a license at the start of the file and before the module-level doc comments. For example: ```typ From 9054b278530277dfa6092f12150a8ee3e594d53b Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:25:39 +0800 Subject: [PATCH 17/22] min typst version --- rfcs/0006-doctring-syntax.md | 2 +- rfcs/0006-doctring-syntax.typ | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0006-doctring-syntax.md b/rfcs/0006-doctring-syntax.md index f8fbc33..bc26fe4 100644 --- a/rfcs/0006-doctring-syntax.md +++ b/rfcs/0006-doctring-syntax.md @@ -455,7 +455,7 @@ Two main factors can affect the backward compatibility: - The typst version to render the docstring. - The docstring processor used to process the docstring. -Since the prelude is defined in `typst.toml`, a minimal typst version can be specified, which determines the default prelude and compiler to render the docstring. Besides `min-version`, A `typst-version` is suggested to added to `typst.toml` to tell which typst version ensures to render the typst syntax used by docstring. +Since the prelude is defined in `typst.toml`, a minimal typst version can be specified, which determines the default prelude and compiler to render the docstring, ensuring to render the typst syntax used by docstring. ## Discussion: Customizing the docstring handlers diff --git a/rfcs/0006-doctring-syntax.typ b/rfcs/0006-doctring-syntax.typ index 5ba7eca..d7f0842 100644 --- a/rfcs/0006-doctring-syntax.typ +++ b/rfcs/0006-doctring-syntax.typ @@ -449,7 +449,7 @@ Two main factors can affect the backward compatibility: - The typst version to render the docstring. - The docstring processor used to process the docstring. -Since the prelude is defined in `typst.toml`, a minimal typst version can be specified, which determines the default prelude and compiler to render the docstring. Besides `min-version`, A `typst-version` is suggested to added to `typst.toml` to tell which typst version ensures to render the typst syntax used by docstring. +Since the prelude is defined in `typst.toml`, a minimal typst version can be specified, which determines the default prelude and compiler to render the docstring, ensuring to render the typst syntax used by docstring. = Discussion: Customizing the docstring handlers From 9b46e589f19b6f2ef80a45e8eaae75c61648c7d4 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:26:45 +0800 Subject: [PATCH 18/22] less terms --- rfcs/0006-doctring-syntax.md | 4 ++-- rfcs/0006-doctring-syntax.typ | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/rfcs/0006-doctring-syntax.md b/rfcs/0006-doctring-syntax.md index bc26fe4..617d044 100644 --- a/rfcs/0006-doctring-syntax.md +++ b/rfcs/0006-doctring-syntax.md @@ -457,11 +457,11 @@ Two main factors can affect the backward compatibility: Since the prelude is defined in `typst.toml`, a minimal typst version can be specified, which determines the default prelude and compiler to render the docstring, ensuring to render the typst syntax used by docstring. -## Discussion: Customizing the docstring handlers +## Discussion: Customized docstring processor _Docstring processors_ can add show rules to customize the docstring rendering. In the sample prelude implementation, the prelude can do nothing if the host doesn't implement a tidy defined docs interfaces and the parameter docs are left in the "base docs" and shown to the users. -The best practice or design pattern for _docstring processors_ to customize the docstring handlers is out of the scope of this RFC, which only discusses the syntax of docstrings. +The best practice or design pattern to customize a docstring processor is out of the scope of this RFC, which only discusses the syntax of docstrings. ## Discussion: Error tolerance diff --git a/rfcs/0006-doctring-syntax.typ b/rfcs/0006-doctring-syntax.typ index d7f0842..2f67cce 100644 --- a/rfcs/0006-doctring-syntax.typ +++ b/rfcs/0006-doctring-syntax.typ @@ -451,11 +451,11 @@ Two main factors can affect the backward compatibility: Since the prelude is defined in `typst.toml`, a minimal typst version can be specified, which determines the default prelude and compiler to render the docstring, ensuring to render the typst syntax used by docstring. -= Discussion: Customizing the docstring handlers += Discussion: Customized docstring processor _Docstring processors_ can add show rules to customize the docstring rendering. In the sample prelude implementation, the prelude can do nothing if the host doesn't implement a tidy defined docs interfaces and the parameter docs are left in the "base docs" and shown to the users. -The best practice or design pattern for _docstring processors_ to customize the docstring handlers is out of the scope of this RFC, which only discusses the syntax of docstrings. +The best practice or design pattern to customize a docstring processor is out of the scope of this RFC, which only discusses the syntax of docstrings. = Discussion: Error tolerance From e3ec8364f8f50594c0c64de49b2430a2e2cb75f0 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:28:56 +0800 Subject: [PATCH 19/22] Use raw code --- rfcs/0006-doctring-syntax.md | 2 +- rfcs/0006-doctring-syntax.typ | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0006-doctring-syntax.md b/rfcs/0006-doctring-syntax.md index 617d044..ecf3862 100644 --- a/rfcs/0006-doctring-syntax.md +++ b/rfcs/0006-doctring-syntax.md @@ -477,7 +477,7 @@ If the newline is preserved in the docstring, the documentation in CJK may be re #let id(x) = x ``` -The content of the above docstring may be "你好n世界" (Unicode `U+4F60 U+597D U+FF0C U+0A U+4E16 U+754C`) and rendered as "你好， 世界" (Unicode `U+4F60 U+597D U+FF0C U+20 U+4E16 U+754C`). +The content of the above docstring may be `你好\n世界` (Unicode `U+4F60 U+597D U+FF0C U+0A U+4E16 U+754C`) and rendered as `你好， 世界` (Unicode `U+4F60 U+597D U+FF0C U+20 U+4E16 U+754C`). Since a package may target non-programming users and non-English speakers, the internationalization of docstrings is considered a important issue. diff --git a/rfcs/0006-doctring-syntax.typ b/rfcs/0006-doctring-syntax.typ index 2f67cce..0c60a88 100644 --- a/rfcs/0006-doctring-syntax.typ +++ b/rfcs/0006-doctring-syntax.typ @@ -471,7 +471,7 @@ If the newline is preserved in the docstring, the documentation in CJK may be re #let id(x) = x ``` -The content of the above docstring may be "你好\n世界" (Unicode `U+4F60 U+597D U+FF0C U+0A U+4E16 U+754C`) and rendered as "你好， 世界" (Unicode `U+4F60 U+597D U+FF0C U+20 U+4E16 U+754C`). +The content of the above docstring may be `你好\n世界` (Unicode `U+4F60 U+597D U+FF0C U+0A U+4E16 U+754C`) and rendered as `你好， 世界` (Unicode `U+4F60 U+597D U+FF0C U+20 U+4E16 U+754C`). Since a package may target non-programming users and non-English speakers, the internationalization of docstrings is considered a important issue. From cc5b54200eae74ed8e5bf85d5aebd08fde30f760 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:29:51 +0800 Subject: [PATCH 20/22] Clarify unresolved issues in docstring internationalization --- rfcs/0006-doctring-syntax.md | 2 +- rfcs/0006-doctring-syntax.typ | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0006-doctring-syntax.md b/rfcs/0006-doctring-syntax.md index ecf3862..cbe9e3e 100644 --- a/rfcs/0006-doctring-syntax.md +++ b/rfcs/0006-doctring-syntax.md @@ -481,4 +481,4 @@ The content of the above docstring may be `你好\n世界` (Unicode `U+4F60 U+59 Since a package may target non-programming users and non-English speakers, the internationalization of docstrings is considered a important issue. -These issues are left as an unresolved in this RFC. +The two issues in this section are left as an unresolved in this RFC. diff --git a/rfcs/0006-doctring-syntax.typ b/rfcs/0006-doctring-syntax.typ index 0c60a88..7f4f420 100644 --- a/rfcs/0006-doctring-syntax.typ +++ b/rfcs/0006-doctring-syntax.typ @@ -475,4 +475,4 @@ The content of the above docstring may be `你好\n世界` (Unicode `U+4F60 U+59 Since a package may target non-programming users and non-English speakers, the internationalization of docstrings is considered a important issue. -These issues are left as an unresolved in this RFC. +The two issues in this section are left as an unresolved in this RFC. From 299a1a25f540b951fcaca73008fa1e9bc3aaa3c0 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:34:44 +0800 Subject: [PATCH 21/22] fix: bad code --- rfcs/0006-doctring-syntax.md | 4 ++-- rfcs/0006-doctring-syntax.typ | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/rfcs/0006-doctring-syntax.md b/rfcs/0006-doctring-syntax.md index cbe9e3e..b1aab11 100644 --- a/rfcs/0006-doctring-syntax.md +++ b/rfcs/0006-doctring-syntax.md @@ -185,10 +185,10 @@ In Issue 1.1, we mentioned that _Docstring processors_ and developers can add de /// ``` let run() = todo() - return r( + return ( configure: configure, run: run, - )un + ) } #let pkg = new() ```` diff --git a/rfcs/0006-doctring-syntax.typ b/rfcs/0006-doctring-syntax.typ index 7f4f420..f7a0876 100644 --- a/rfcs/0006-doctring-syntax.typ +++ b/rfcs/0006-doctring-syntax.typ @@ -191,10 +191,10 @@ In Issue 1.1, we mentioned that _Docstring processors_ and developers can add de /// ``` let run() = todo() - return r( + return ( configure: configure, run: run, - )un + ) } #let pkg = new() ```` From 0cbd406febd74b633301a9bb9ef18a1442bbd71f Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Sat, 13 Sep 2025 10:40:22 +0800 Subject: [PATCH 22/22] edit sample impl --- rfcs/0006-doctring-syntax.md | 2 +- rfcs/0006-doctring-syntax.typ | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0006-doctring-syntax.md b/rfcs/0006-doctring-syntax.md index b1aab11..ebb487d 100644 --- a/rfcs/0006-doctring-syntax.md +++ b/rfcs/0006-doctring-syntax.md @@ -420,7 +420,7 @@ Sample prelude implementation: #let example(it) = it.text #show: it => { show ref: it => { - if tidy-version >= version(0, 4, 0) { + if tidy-version >= version(0, 4, 0) and tidy-version < version(0, 5, 0) { tidy-render-reference(it) // Provided by tidy or tinymist processor } else { it diff --git a/rfcs/0006-doctring-syntax.typ b/rfcs/0006-doctring-syntax.typ index f7a0876..9041df1 100644 --- a/rfcs/0006-doctring-syntax.typ +++ b/rfcs/0006-doctring-syntax.typ @@ -415,7 +415,7 @@ Sample prelude implementation: #let example(it) = it.text #show: it => { show ref: it => { - if tidy-version >= version(0, 4, 0) { + if tidy-version >= version(0, 4, 0) and tidy-version < version(0, 5, 0) { tidy-render-reference(it) // Provided by tidy or tinymist processor } else { it