IDE Integration

LPCDoc is designed to work with modern development tools and IDEs. This section explains how LPCDoc comments can enhance your development experience through integration with code editors.

VS Code Extension

The VS Code extension LPC Language Services provides rich language support for LPC, including integration with LPCDoc comments.

Features

When using LPCDoc comments with the LPC Language Services extension, you gain access to:

• IntelliSense and Code Completion - Type information from LPCDoc comments is used to provide better suggestions
• Hover Information - See documentation when hovering over functions and variables
• Signature Help - Parameter information appears as you type function calls
• Type Checking - The extension uses type annotations to validate your code

Type Annotations

Type annotations in LPCDoc comments provide additional context to language servers and IDEs. While these annotations are optional, they significantly enhance code intelligence features.

Basic Syntax

The basic syntax for type annotations is:

/**
 * @param {type} name - Description of the parameter
 * @returns {type} Description of the return value
 */

Practical Examples

Here are some practical examples of LPCDoc comments with type annotations that work with the LPC Language Services extension:

/**
 * Attempts to run a command
 * @param {string} cmd - The command to run
 * @returns {int} 1 if successful, otherwise 0
 */
int doCommand(string cmd) {
    return 1;
}

For specifying object types:

/**
 * @param {"/std/player.c"} player - The player to welcome
 */
void welcomePlayer(object player) {
    write("Hi " + player->query_name());
}

For variable annotations:

/** @type {"/std/weapon.c"} */
object weapon;

For return type annotations:

/**
 * @returns {"/std/player.c"} The current player object
 */
object getPlayer() {
    return lookupPlayer();
}

Special Directives

The LPC Language Services extension also supports special directives that interact with the type checking system:

@lpc-ignore

Instructs the checker to ignore errors on a single line:

// @lpc-ignore - ignore int to string assignment error
string foo = 123;

@lpc-nocheck

Disables diagnostics for an entire file:

// @lpc-nocheck
... statements

@lpc-check

Re-enables diagnostics for a file — the inverse of @lpc-nocheck. Use it to turn checking back on for files that would otherwise be skipped:

// @lpc-check
... statements

@lpc-expect-error

Indicates that the next line is expected to return an error:

// @lpc-expect-error: method does not exist
o->foo();

@this_object

Overrides the object type of this_object():

// @this_object /std/living

Setting Up IDE Integration

To fully utilize LPCDoc in your IDE, refer to the documentation for the LPC Language Services extension. In general, you’ll need to:

1. Install the extension from the VS Code Marketplace
2. Create an lpc-config.json file in your workspace root
3. Configure include paths and other settings
4. Enable diagnostics to benefit from type checking

Properly configured, your LPCDoc comments will provide rich contextual information throughout your development workflow.