From 9632deccc7463f1f05bb12aea89bee82f857e089 Mon Sep 17 00:00:00 2001
From: Pat Garrity <pfm@garrity.co>
Date: Tue, 23 Jul 2024 13:29:32 -0500
Subject: [PATCH] Added comment documentation.

---
 docs/revision2.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/docs/revision2.md b/docs/revision2.md
index 8b90aec..20b4c04 100644
--- a/docs/revision2.md
+++ b/docs/revision2.md
@@ -11,6 +11,7 @@ started 2024-07-18.
 - [Namespaces](#namespaces)
 - [Imports](#imports)
 - [Definitions](#definitions)
+- [Comments](#comments)
 
 ## Names
 
@@ -194,6 +195,7 @@ TODO: Consider `abstract` to be used for abstract type class functions.
 ### `->` (Type Function Operator)
 ### `_` (Anonymous Value Binding)
 ### `|` (Type Union Operator)
+### `--` (Comment Prefix)
 
 ## Namespaces
 
@@ -294,3 +296,37 @@ that they are shared across files that share a namespace.
 
 `private` definitions are only accessible _within their file_. Even if another
 file shares a namespace, `private` definitions are invisible to that file.
+
+## Comments
+
+_Comments_ are sections of code that are not parsed as code. They are used to
+add in-code documentation.
+
+### Rules
+
+- All comments begin with `--`. This is a _prefix_, `--` tells the parser to
+  ignore any following content on sight.
+- Multi-line comments are **not** supported.
+- Names may _not_ include the comment designator.
+
+### Standard Comment Syntax
+
+Comments start with `--`. If that string is detected, the comment initializer to
+the end of the line will be completely ignored.
+
+### Docstring Comment Syntax
+
+Docstrings start with `---` and must precede a _definition_ at the top level of
+some source file. Docstrings _may_ be parsed in a separate process to produce a
+documentation artifact.
+
+### Examples
+
+```
+--- This is a docstring for the function definition.
+fn foo: String -> String
+    -- This is a regular comment.
+    --- This is a regular comment, because it is not at the definition level.
+    λ x => x + x
+end fn
+```