📚 KDocs - Documentação Nativa Universal#

O KDocs (src/editor/kdocs.py) é o sistema de documentação integrado ao Codis. Ele analisa comentários e docstrings nativamente em 27 linguagens (mais um perfil genérico de fallback) e exibe um balloon de documentação rico ao passar o mouse sobre qualquer símbolo documentado - sem depender de LSP.

O Que é o KDocs?#

O KDocs é um motor de análise estática que funciona diretamente sobre o texto do arquivo, detectando automaticamente o estilo de documentação pela extensão do arquivo:

• Detecção automática de linguagem - .py → Python, .rs → Rust, .go → Go, etc.
• Badge de linguagem colorido no balloon - PYTHON azul #3572a5, RUST laranja #dea584, GO ciano #00add8
• Múltiplos estilos por linguagem - Python suporta Google Style, NumPy Style e Sphinx/reST simultaneamente
• Anotações @kdocs: em qualquer linguagem (comentários da própria linguagem)
• Cache LRU de 64 entradas para performance em arquivos grandes
• Integração com o Painel Docs - lista filtrável de todos os símbolos documentados do arquivo ativo

Detecção Automática de Linguagem#

O KDocs detecta a linguagem pela extensão do arquivo e seleciona o parser correto. Ao todo são 27 perfis de linguagem (LanguageProfile) mais um perfil genérico de fallback:

Linguagens sem cor de badge própria no código (SQL, Shell, YAML, HTML, CSS, SCSS, JSX, TOML) usam a cor padrão lilás #cba6f7 reservada para jsdoc/fallback.

Estilos de Documentação Suportados#

JavaScript / TypeScript - JSDoc / TSDoc#

/**
 * Calcula o fatorial de um número.
 * @param {number} n - O número inteiro não negativo.
 * @returns {number} O fatorial de n.
 * @throws {Error} Se n for negativo.
 * @example
 * factorial(5); // 120
 */
function factorial(n) { ... }

Tags JSDoc reconhecidas: @param, @returns, @throws, @example, @deprecated, @since, @author, @see, @type, @typedef, @callback, @template, @override, @abstract.

Python - Google Style#

def divide(a: float, b: float) -> float:
    """Divide dois números.

    Args:
        a: Numerador.
        b: Denominador. Não pode ser zero.

    Returns:
        O resultado da divisão.

    Raises:
        ValueError: Se b for zero.

    Example:
        >>> divide(10, 2)
        5.0
    """

Python - NumPy Style#

def soma(a, b):
    """
    Soma dois valores.

    Parameters
    ----------
    a : int
        Primeiro operando.
    b : int
        Segundo operando.

    Returns
    -------
    int
        Resultado da soma.
    """

Python - Sphinx / reST#

def greet(name: str) -> str:
    """Gera uma saudação.

    :param name: Nome da pessoa.
    :type name: str
    :returns: String de saudação.
    :rtype: str
    :raises TypeError: Se name não for string.
    """

Rust - Doc Comments (///)#

/// Calcula a raiz quadrada de um número.
///
/// # Arguments
///
/// * `x` - O número a calcular. Deve ser não negativo.
///
/// # Returns
///
/// A raiz quadrada de `x`.
///
/// # Panics
///
/// Entra em panic se `x` for negativo.
pub fn sqrt(x: f64) -> f64 { ... }

Go - Godoc#

// Fetch realiza uma requisição HTTP GET para a URL fornecida.
// Retorna o corpo da resposta como string ou um erro.
// Exemplo:
//
//	body, err := Fetch("https://example.com")
func Fetch(url string) (string, error) { ... }

Ruby - YARD#

# Calcula o IMC de uma pessoa.
#
# @param peso [Float] Peso em quilogramas.
# @param altura [Float] Altura em metros.
# @return [Float] O índice de massa corporal.
# @raise [ArgumentError] Se altura for zero.
def imc(peso, altura)

Lua - LDoc#

--- Faz login no servidor.
-- @param usuario string O nome de usuário.
-- @param senha string A senha do usuário.
-- @return boolean true se o login foi bem-sucedido.
-- @usage login("admin", "senha123")
function login(usuario, senha)

Doxygen (C/C++/PHP/Java)#

/**
 * @brief Inicializa o módulo de rede.
 *
 * @param host Endereço do servidor.
 * @param port Porta de conexão (padrão: 8080).
 * @return int 0 em sucesso, código de erro negativo em falha.
 * @warning Esta função não é thread-safe.
 */
int net_init(const char* host, int port);

C# - XML Documentation#

/// <summary>
/// Converte uma string para Base64.
/// </summary>
/// <param name="input">A string a ser codificada.</param>
/// <returns>A representação Base64 da string.</returns>
/// <exception cref="ArgumentNullException">Se input for null.</exception>
public static string ToBase64(string input) { ... }

Anotações KDocs Especiais#

As anotações @kdocs:<tipo> funcionam em qualquer linguagem, independente do estilo de comentário (//, #, --, <!-- -->). O <tipo> não é uma lista fechada pré-definida - o parser aceita qualquer palavra após @kdocs:, mas os tipos abaixo têm tratamento e renderização especiais no balloon:

# @kdocs:since 1.0.0
# @kdocs:author KillovSky
# @kdocs:stability stable
# @kdocs:warn [fs] Não use de forma síncrona em produção! [@alice] [!high] [#nosync]
# [!due:2025-12-31]
# [!ticket:PROJ-123]
def minha_funcao():
    ...

Modificadores entre colchetes#

Podem ser combinados livremente dentro do texto de qualquer anotação @kdocs::

URLs em qualquer anotação são convertidas em links clicáveis no balloon.

Balloon de Documentação#

Ao passar o mouse sobre um símbolo documentado, um balloon é exibido com:

• Badge de linguagem - identifica visualmente a linguagem do arquivo
• Nome do símbolo e tipo (função, classe, variável)
• Descrição extraída do comentário
• Parâmetros com tipos e descrições
• Retorno com tipo e descrição
• Exceções / Erros documentados
• Exemplos de uso com syntax highlighting
• Metadados KDocs (@since, @author, [!ticket:], [!due:])
• Locais de uso do símbolo no arquivo (até 200 ocorrências escaneadas)

O balloon usa debounce para evitar disparos acidentais e fecha automaticamente ao mover o cursor.

Cache LRU#

O KDocs mantém um cache LRU (_DocCache) com capacidade de 64 entradas. Arquivos grandes com muitas definições são parseados uma única vez e os resultados ficam em cache até que o conteúdo do arquivo mude.

Configuração#

Painel KDocs na Sidebar#

O painel 📚 KDocs (Activity Bar → 📚) exibe uma navegação estruturada de todas as definições documentadas do arquivo ativo. Clique em qualquer entrada para ir à definição.

Compatibilidade#

O KDocs é compatível com JSDoc. Nenhuma migração de comentários é necessária - o motor detecta automaticamente o estilo usado.

O KDocs opera de forma complementar ao LSP: quando um servidor de linguagem está ativo e fornece hover documentation, o LSP tem prioridade. O KDocs é o fallback quando o LSP não está disponível ou não possui documentação para o símbolo.