/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Concepts Annotation Reference

Annotation Reference

Complete reference for @stx annotations and zero-config doc comment parsing across all supported languages.

6 min read

Syntext extracts API documentation from source code using a two-tier system: standard doc comments work with zero configuration, and optional @stx directives give you enhanced control.

Priority Rule

If a comment block contains any @stx directive, the entire block is parsed by the @stx parser and conventional tags are ignored:

typescript
/**
* @stx group "Authentication"
* @stx title "Login"
* @stx param credentials {Credentials} User login credentials
*/
export function login(credentials: Credentials): Token { ... }

Supported Languages

LanguageExtensionsComment styleZero-config format
TypeScript / JavaScript.ts .tsx .mts .cts .js .jsx .mjs .cjs/** ... */, /// ...JSDoc
Python.py"""..."""Google, NumPy, Sphinx/reST
Go.go// ...Go doc conventions
Rust.rs/// ..., //! ...Markdown # Sections
Java / Kotlin.java .kt .kts/** ... */Javadoc
PHP.php/** ... */PHPDoc
C#.cs/// <summary>XML doc comments
Ruby.rb# ..., =begin ... =end@stx directives — hosted builds only; the stx CLI has no local Ruby parser

Tier 1: Zero-Config Doc Comments

Your existing doc comments are parsed automatically — no changes required.

TypeScriptPythonGoRustJavaPHPC#
typescript
/**
* Creates a new user account.
* @param {string} name - The user display name
* @param {string} email - The user email
* @returns {Promise<User>} The created user
* @since v2.0
* @deprecated Use createUserV2 instead
* @category Authentication
* @example
* const user = await createUser("Alice", "alice@example.com")
*/
export async function createUser(name: string, email: string): Promise<User> { }

Supported tags: @param, @returns / @return, @deprecated, @since, @see, @example, @internal / @private / @hidden (excludes from docs), @category / @group / @module (grouping). Optional params via @param {type} [name].

Tier 2: @stx Directives

All directives follow @stx <directive> [value] and work inside any supported comment style.

DirectiveValueDescription
@stx group "Name"Quoted stringSidebar group for the generated page
@stx title "Name"Quoted stringDisplay title (default: symbol name)
@stx description "Text"String or multilineMarkdown description
@stx param name {type} descriptionMixedParameter documentation
@stx returns {type} descriptionMixedReturn value documentation
@stx example "title"Block until next directiveCode example
@stx since versionStringVersion introduced
@stx deprecated "message"Optional stringDeprecation notice
@stx internalFlagHide from public documentation
@stx see referenceStringCross-reference to another symbol

Example in Python (comment-style directives also work):

python
# @stx group "Database"
# @stx title "Execute Query"
def execute_query(sql: str, params: dict = None) -> list:
"""
@stx param sql {str} The SQL query string
@stx param params {dict} Optional query parameters
@stx returns {list} Query results
"""

Symbol Types Detected

KindLanguages
functionAll (function, def, func, fn, arrow functions)
classAll (class, struct in Go/Rust/C#, record in C#)
interfaceTypeScript, Go, Java, C# (trait in Rust)
typeTypeScript, Go
enumTypeScript, Java, Rust, PHP, C#
methodGo (receivers), Java, C#
propertyC# ({ get; set; })

Embedding Symbols in MDX

Any docs page can pull an @stx-annotated symbol's source code in as a highlighted code block. Put each directive on its own line:

mdx
## Create a user
{@embed createUser}
## Delete a user
{@embed src="src/admin/users.ts#deleteUser"}
FormEmbeds
{@embed symbolName}The annotated symbol with that name, from anywhere in your repository
{@embed src="path#symbolName"}That symbol in that file. The path is relative to the repository root.

Hosted builds take embedded code from your connected repository, at the commit being built. The result is a code block in the file's language, titled with the file path. It holds the symbol's declaration and body; the @stx comment above it is left out. When your code changes, the next build picks up the new version. A push that only changes embedded code still rebuilds the page.

•
Only annotated symbols can be embedded. The symbol needs an @stx comment directly above it.
•
Same name in two files? {@embed name} uses the first file in path order, and the build log warns you and names every file. Use the src="path#name" form to choose one.
•
Writing about the syntax? Directives inside code blocks, inline code and frontmatter are left alone. This page uses that to show the examples above.
•
Can't be resolved? If the symbol or file doesn't exist, the src value has no #symbol, or the directive shares its line with other text, the page shows a visible "Embed not resolved" warning in its place. The build log gets a {@embed}: docs/page.mdx:12: … warning with the reason. The build still succeeds.
Note

Embeds resolve in builds from a connected Git repository. stx deploy uploads only docs/, public/ and your API specs, so code outside docs/ isn't available to an uploaded build, and its embeds show the warning. stx build and stx dev don't resolve embeds yet. stx generate resolves {@embed symbolName} locally — it rewrites the directive in your page file with the symbol's generated section.

Drift Detection

Syntext records each documented symbol's signature (name, parameter names/types/optionality, return type). When the code changes but the docs don't, stx check reports drift — so stale docs get caught in CI, not by your users.

bash
stx check --save-hashes # once: record the current signatures in .syntext/hashes.json (commit it)
stx check --strict # in CI: drift fails the run (without --strict it's a warning)
Note

See Generating API Docs for a step-by-step walkthrough, and CI/CD for running drift checks in your pipeline.

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext