---
title: Annotation Reference
description: "Complete reference for @stx annotations and zero-config doc comment parsing across all supported languages."
---

# Annotation Reference

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

| Language | Extensions | Comment style | Zero-config format |
|----------|-----------|---------------|--------------------|
| TypeScript / JavaScript | `.ts` `.tsx` `.js` `.jsx` | `/** ... */`, `/// ...` | 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 |

## Tier 1: Zero-Config Doc Comments

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

<Tabs>
<Tab title="TypeScript">
```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]`.
</Tab>
<Tab title="Python">
Google, NumPy, and Sphinx/reST docstring styles are all recognized:

```python
def fetch_user(user_id: str, include_profile: bool = False) -> User:
    """Fetches a user from the database.

    Args:
        user_id (str): The unique user identifier
        include_profile (bool, optional): Whether to include profile data

    Returns:
        User: The found user object

    Raises:
        NotFoundError: If user doesn't exist

    Examples:
        >>> user = fetch_user("abc123")
    """
```

Recognized sections: `Args:` / `Arguments:` / `Parameters:`, `Returns:`, `Raises:`, `Example(s):`, `Attributes:`, plus reST `:param:` / `:type:` / `:returns:` / `:rtype:` and NumPy `Parameters ----------` style.
</Tab>
<Tab title="Go">
```go
// NewClient creates a new API client with the given configuration.
// It validates the config and returns an error if the provided
// endpoints are unreachable.
func NewClient(config Config) (*Client, error) { }

// Deprecated: Use NewClientV2 instead.
func OldClient() *Client { }
```

The comment block becomes the description. A `Deprecated:` prefix marks the symbol deprecated.
</Tab>
<Tab title="Rust">
```rust
/// Creates a new buffer with the specified capacity.
///
/// # Arguments
///
/// * `capacity` - Initial capacity in bytes
///
/// # Returns
///
/// A new empty buffer.
///
/// # Examples
///
/// ```rust
/// let buf = Buffer::new(1024);
/// ```
pub fn new(capacity: usize) -> Buffer { }
```

Recognized sections: `# Arguments` / `# Parameters`, `# Returns`, `# Example(s)`, `# Panics`, `# Errors`, `# Safety`.
</Tab>
<Tab title="Java">
```java
/**
 * Creates a new user in the system.
 *
 * @param username the desired username
 * @param email the user email address
 * @return the created User object
 * @since 2.0
 * @see UserService
 */
public User createUser(String username, String email) { }
```

Same tag set as JSDoc. Framework annotations (`@Override`, `@Autowired`, …) on the definition line are skipped.
</Tab>
<Tab title="PHP">
```php
/**
 * Sends an email notification to the user.
 *
 * @param string $to The recipient email address
 * @param string $subject The email subject line
 * @return bool Whether the email was sent successfully
 * @category Notifications
 */
function sendEmail(string $to, string $subject): bool { }
```

The `$` prefix on parameter names is normalized automatically.
</Tab>
<Tab title="C#">
```csharp
/// <summary>
/// Creates a new user account in the system.
/// </summary>
/// <param name="username">The desired username</param>
/// <returns>The created user object</returns>
/// <seealso cref="UpdateUser"/>
public async Task<User> CreateUser(string username, string email) { }
```

Recognized elements: `<summary>`, `<remarks>`, `<param>`, `<returns>`, `<example>` / `<code>`, `<see>` / `<seealso>`, `<paramref>`, `<c>`. Attributes like `[HttpGet]` are skipped.
</Tab>
</Tabs>

## 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):

```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

| 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 embed generated symbol documentation inline:

```mdx
## API Reference

{@embed createUser}

{@embed deleteUser}
```

The embed is replaced at build time with the rendered documentation for that symbol.

## Drift Detection

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

```bash
stx check          # exits non-zero if drift is detected
```

<Note>
See [Generating API Docs](/guides/api-documentation) for a step-by-step walkthrough, and [CI/CD](/guides/ci-cd) for running drift checks in your pipeline.
</Note>