Annotation Reference
Complete reference for @stx annotations and zero-config doc comment parsing across all supported languages.
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:
Supported Languages
| Language | Extensions | Comment style | Zero-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.
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].
Google, NumPy, and Sphinx/reST docstring styles are all recognized:
Recognized sections: Args: / Arguments: / Parameters:, Returns:, Raises:, Example(s):, Attributes:, plus reST :param: / :type: / :returns: / :rtype: and NumPy Parameters ---------- style.
The comment block becomes the description. A Deprecated: prefix marks the symbol deprecated.
Recognized sections: # Arguments / # Parameters, # Returns, # Example(s), # Panics, # Errors, # Safety.
Same tag set as JSDoc. Framework annotations (@Override, @Autowired, …) on the definition line are skipped.
The $ prefix on parameter names is normalized automatically.
Recognized elements: <summary>, <remarks>, <param>, <returns>, <example> / <code>, <see> / <seealso>, <paramref>, <c>. Attributes like [HttpGet] are skipped.
Tier 2: @stx Directives
All directives follow @stx <directive> [value] and work inside any supported comment style.
| Directive | Value | Description |
|---|---|---|
@stx group "Name" | Quoted string | Sidebar group for the generated page |
@stx title "Name" | Quoted string | Display title (default: symbol name) |
@stx description "Text" | String or multiline | Markdown description |
@stx param name {type} description | Mixed | Parameter documentation |
@stx returns {type} description | Mixed | Return value documentation |
@stx example "title" | Block until next directive | Code example |
@stx since version | String | Version introduced |
@stx deprecated "message" | Optional string | Deprecation notice |
@stx internal | Flag | Hide from public documentation |
@stx see reference | String | Cross-reference to another symbol |
Example in Python (comment-style directives also work):
Symbol Types Detected
| Kind | Languages |
|---|---|
function | All (function, def, func, fn, arrow functions) |
class | All (class, struct in Go/Rust/C#, record in C#) |
interface | TypeScript, Go, Java, C# (trait in Rust) |
type | TypeScript, Go |
enum | TypeScript, Java, Rust, PHP, C# |
method | Go (receivers), Java, C# |
property | C# ({ 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:
| Form | Embeds |
|---|---|
{@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.
@stx comment directly above it.{@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.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.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.
See Generating API Docs for a step-by-step walkthrough, and CI/CD for running drift checks in your pipeline.