Various suggestions regarding syntax

src/chapters/api/documentation.typ

@@ -9,7 +9,7 @@ An item may be a state variable, a counter, a function, a reusable piece of regu
   For the exact syntax used for documentation comments, refer to @sec:style:docs.
 ]
 
-For functions a public API should always document all public arguments, their usage and purpose as well as constraints on their values.
+For public functions the documentation should always incldue all public parameters, their usage and purpose as well as possible constraints on their values.
 Internal arguments may be ommited, if they are not meant to be exposed to a user, but should still be documented for contributors in the source or a contribution document.
 Depending on the doc aprser in use, named arguments may need their defaults explicitly stated and should have if the doc parser can't parse them automatically.
 If functions require or return contextual values, this should also be communicated clearly.

src/chapters/style/documentation.typ

@@ -6,58 +6,233 @@
   This section documents the syntax of documentation commens, see @sec:api:docs for the contents and purpose of documentation comments.
 ]
 
-Documentation for items are placed on comments right before the item, with three forward slashes `///` and a leading space.
-The first leading space and comment tokens are stripped of the line and each line is joined to make up the body of the doc comment.
-The content of doc comments should be simple Typst markup with some extra documentation specific syntax and assumptions about structure.
-Doc comments do not use any other strucutre at this moment, regular comments `//` and `/**/` are ignored by most doc parsers.
+Documentation is placed on special comments using three forward slashes `///` and an optional space.
+These are called doc comments.
+While the leading space is optional, it is encouraged as it makes the documentaiton easier to read.
+Doc comments may not be interrupted by empty lines, markup, or regular comments.
 
 #do-dont[
   ```typst
-  /// This is a doc comment
-  #let item = ...
+  /// A1
+  /// A2
+  /// A3
+
+  // discuraged, but valid
+  ///B1
+  ///B2
+  ///B3
   ```
 ][
   ```typst
+  /// A1
+  //
+  /// B1
+
+  /// A1
+
+  /// B1
+
+  /// C1
+  Hello World
+  /// D1
+
   /**
-   * This is not a doc comment, it's a regular comment.
+   * This is a regular comment, not a doc comment.
    */
-  #let item = ...
+  #let item = { ... }
 
-  // This is not a doc comment, it's a regular comment.
-  #let item = ...
+  // This is a regular comment, not a doc comment.
+  #let item = { ... }
   ```
 ]
 
-Doc comments are split into two parts:
-- the general description, including examples and package specific sections and the
-- optional trailer containing semantic information about the annotated item.
+There are two kinds of documentation comments, inner and outer doc comments.
+Outer doc comments are placed right above the declaration they are attached to.
 
-Doc comments may include special syntax such as `@@val` or `@@func()`, these are used by doc generators like #mty.package[Tidy] to generate cross references in documentation.
+#do-dont[
+  ```typst
+  /// Documentation for func
+  #let func() = { ... }
 
-#wbox[
-  There seems to be no special syntax to refer to things other than functions and values at this moment.
+  ```
+][
+  ```typst
+  /// Stray doc comment, not the doc for func
+
+  #let func() = {
+    /// Stray doc comment, not the doc for func
+    ...
+  }
+
+  /// Stray doc comment, not the doc for func
+  ```
+]
+
+Inner doc comments are used to document modules and must not have a declaration, instead they refer to the file they are placed in and may only be declared once and as the first non comment item in a file.
+
+#do-dont[
+  ```typst
+  // optional leading comments
+
+  /// Module doc
+
+  /// Function or value doc
+  #let item = { ... }
+  ```
+][
+  ```typst
+  /// Function or valtion doc
+  #let item = { ... }
+
+  /// Stray doc comment, not the module or func doc
+  ```
+]
+
+Outer doc comments may be used on `let` bindings only.
+
+#do-dont[
+  ```typst
+  /// Function doc
+  #let func() = { ... }
+
+  /// Value doc
+  #let value = { ... }
+  ```
+][
+  ```typst
+  /// Stray doc comment, markup may not be documented
+  Hello World
+
+  /// Stray doc comment, imports my not be documented
+  #import "module.typ"
+
+  /// Stray doc comment, scopes may not be documented
+  #[
+    ...
+  ]
+  ```
 ]
 
+Doc comments contain a description of the documented item itself, as well as an optional semantic trailer.
+The content of descriptions should generally be simple Typst markup and should not contain any scripting, (i.e. no loops, conditionals or function calls, except for `#link("...")[...]`), this allows the documentation to be turned into Markdown or plaintext or LSP to send to editors.
+
 == Description
-The general description makes no assumptions on syntax other than including the aforementioned cross-reference syntax.
-It may be any Typst syntax, but should ideally kept simple to allow LSPs to convert it into Markdown for editor hover actions.
+As mentioned before, the description should be simple, containing mostly markup and no scripting.
 
 == Semantic Trailer
-The semantic trailer of doc comments is the last section of the doc comments containing optional information about the documented item.
-This may include a list of parameter descriptions, a return type annotation, and other annotations, all of which are not treated as regular Typst syntax.
-
-At this moment #mty.package[Tidy] accepts the following syntax:
-```ebnf
-param-name          ::= typst-ident
-type-name           ::= typst-ident
-type                ::= ( '..' )? type-name
-type-list           ::= '(' type ( ',' type )+ ')'
-description         ::= typst-markup
-
-param-documentation ::= '/// - ' param-name ' ' type-list ':' [description]
-return-type         ::= '/// -> ' type-name
-```
-
-As well as some other more specific ones like doc tests.
-We shall only consider this subset for now.
-The trailer may contain zero or more lines of `param-documentation` and an optional `return-type` line.
+The semantic trailer is fully optional, starts with an empty doc comment line to separate it from the description, and may contain:
+- multiple `term` items for parameter type hints and descriptions,
+- a return type hint `-> type`,
+- and multiple property annotations (`#property("private")` or `#property("deprecated")`).
+
+Types in type lists or return type annotations may be separated by `|` to indicate that more than one type is accepted, the exact types allowed depend on the doc parser, but the built in types are generally supported.
+
+Parameter description and return types (if present) are placed tightly together, property annotations if present are separated using another empty doc comment line.
+
+Parameter documentation is created by writing a term item containing the parameter name, a mandatory type list in parenthesis and optional description.
+If the parameter is an argument sink it's name must also containe the spread operator `..`.
+Each parameter can only be documented once, but doesn't have to, undocumented parameters are considered private.
+
+#do-dont[
+  ```typst
+  /// Function description
+  ///
+  /// / b (any): b descpription
+  /// / a (int | float): a description
+  #let func(a, b, c) = { ... }
+
+  /// Function description
+  ///
+  /// / ..args (int): args description
+  #let func(..args) = { ... }
+  ```
+][
+  ```typst
+  /// Function description
+  ///
+  /// / c (any): c doesn't exist
+  /// / a (int | float): a description
+  #let func(a, b) = { ... }
+
+  /// Missing empty line between function description and trailer
+  /// / b (any): b descpription
+  /// / a (int | float): a description
+  #let func(a, b) = { ... }
+
+
+  /// Function description
+  ///
+  /// / b (any): b descpription
+  /// / a: missing types
+  #let func(a, b) = { ... }
+
+  /// Function description
+  ///
+  /// / args (int): missing spread operator for args
+  #let func(..args) = { ... }
+  ```
+]
+
+The return type can only be annotated once, on a single line after all parameters if any exist.
+For non function types the return type annotation can be used as a normal type annotation.
+
+#do-dont[
+  ```typst
+  /// Function doc
+  ///
+  /// / arg (types): Description for arg
+  /// -> types
+  #let func(arg) = { ... }
+
+  /// Value doc
+  ///
+  /// -> type
+  #let value = { ... }
+  ```
+][
+  ```typst
+  /// Missing empty line between description trailer
+  ///
+  /// -> type
+  /// / arg (types): arg descrption after return type
+  #let func(arg) = { ... }
+  ```
+]
+
+Property annotations can be used to document package specific or otherwise important information like deprecation status, visibility or contextuality and may only be used after the return type (if one exists) and an empty doc comment line.
+
+#do-dont[
+  ```typst
+  /// Function doc
+  ///
+  /// / arg (types): Description for arg
+  /// -> types
+  ///
+  /// #property("deprecated")
+  /// #property("contextual")
+  #let func(arg) = { ... }
+
+  /// Value doc
+  ///
+  /// #property("contextual")
+  #let value = { ... }
+  ```
+][
+  ```typst
+  /// Missing empty line between return type and properties
+  ///
+  /// / arg (types): Description for arg
+  /// -> types
+  /// #property("deprecated")
+  /// #property("contextual")
+  #let func(arg) = { ... }
+
+  /// Return type after properties and missing empty separation lines
+  ///
+  /// / arg (types): Description for arg
+  /// #property("deprecated")
+  /// #property("contextual")
+  /// -> types
+  #let func(arg) = { ... }
+  ```
+]