matej/docs-reference-drift

packages/varlock-website/src/content/docs/env-spec/reference.mdx

@@ -98,10 +98,11 @@ ITEM3=
 
 
 ### Config Item Comments
-Comment lines directly preceeding an item will be attached to that item, along with the decorators contained within.
+Comment lines directly preceding an item will be attached to that item, along with the decorators contained within.
 
 - A blank line or a divider will break the above comments from being attached to the item below
 - Both decorator and regular comment lines may be interspersed
+- Standalone comments only count as decorator comments when the comment content starts with `@`
 - Post-value comments may also contain decorators, but should be used sparingly
 
 ```env-spec
@@ -123,9 +124,9 @@ ITEM2=
 A comment block is a group of continuous comments that is not attached to a specific config item.
 
 - The comment block is ended by an empty line, a divider, or the end of the file
-- Any comment blocks before the first config item in a document are considered part of the _document header_
+- All comment blocks before the first config item in a document are considered part of the same _document header_ until one of those endings appears
 - Decorators from this header can be used to configure all contained elements, or the loading process itself
-- We recommend ending the header with a divider for clarity, but it is not required
+- We recommend ending the header with a divider for clarity, but `# ---` is optional
 
 ```env-spec
 # this is the document header and usually contains root decorators

packages/varlock-website/src/content/docs/guides/schema.mdx

@@ -65,8 +65,9 @@ lines
 ### Item comments
 Comments are used to attach additional documentation and metadata to config items using [item decorators](/reference/item-decorators). This additional metadata is used by varlock to perform validation, coercion, and generate types / documentation.
 
-Multiple comment lines _directly_ preceeding an item will be attached to that item. A blank line or a divider (`# ---`) break a comment block, and detach it from the following config item.
-Comment lines can either contain regular comments or [item decorators](/reference/item-decorators). Note that if a line does not start with a decorator, it will be treated as a regular comment.
+Multiple comment lines _directly_ preceding an item will be attached to that item. A blank line or a divider breaks a comment block and detaches it from the following config item.
+Any comment block before the first item is still part of the document header until it is ended by a blank line, a divider, or the end of the file.
+Comment lines can either contain regular comments or [item decorators](/reference/item-decorators). Standalone comments only count as decorator comments when the comment content starts with `@`.
 
 ```env-spec
 # description of item can be multiple lines
@@ -135,4 +136,3 @@ REQUIRED_FOR_PROD=
 
 
 
-

packages/varlock-website/src/content/docs/reference/data-types.mdx

@@ -211,7 +211,7 @@ MY_UUID=123e4567-e89b-12d3-a456-426614174000
 Checks for valid [MD5 hash](https://en.wikipedia.org/wiki/MD5).
 ```env-spec
 # @type=md5
-MY_HASH=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
+MY_HASH=d41d8cd98f00b204e9800998ecf8427e
 ```
 </div>
 

packages/varlock-website/src/content/docs/reference/item-decorators.mdx

@@ -5,9 +5,9 @@ description: A reference page of available env-spec decorators for items
 import Decorator from '@/components/decorator-doc-entry.astro'
 import docsImg from '@/assets/docs/multiple-docs-intellisense.png'
 
-Decorators in a comment block _directly_ preceeding a config item will be attached to that item.
+Decorators in a comment block _directly_ preceding a config item will be attached to that item.
 Multiple decorators can be specified on the same line.
-A comment block is broken by either an empty line or a divider.
+A comment block is broken by either an empty line or a divider (`# ---` is optional, but often used for clarity).
 
 ```env-spec
 # @required @sensitive @type=string(startsWith=sk-)
@@ -19,7 +19,7 @@ More details of the minutiae of decorator handling can be found in the [@env-spe
 
 ## Built-in item decorators
 
-These are the item decorators that are built into Varlock. [Plugins](/guides/plugins/) may introduce more.
+These are the item decorators built into Varlock. [Plugins](/guides/plugins/) can extend the DSL with additional decorators.
 
 <div class="reference-docs">
 <div>
@@ -147,4 +147,20 @@ Use [`@docs()`](#docs) instead, which supports multiple docs entries with option
 
 `@docsUrl=https://example.com` -> `@docs(https://example.com)`
 </div>
+
+<div>
+### `@icon`
+**Value type:** `string`
+
+Attaches an icon identifier to the item, using iconify ids `collection-name:icon-name`. This icon will be included in autogenerated types.
+
+See https://icones.js.org/ to browse available icons.
+
+Useful for generated docs and UI surfaces that show schema metadata.
+
+```env-spec
+# @icon=mdi:key
+SERVICE_X_API_KEY=
+```
+</div>
 </div>