kdocs

📚 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:

Extensão	Linguagem	Estilo detectado	Badge
.py, .pyw, .pyi	Python	Google · NumPy · Sphinx/reST (auto)	PYTHON azul #3572a5
.rs	Rust	/// doc comments com Markdown	RUST laranja #dea584
.go	Go	godoc - comentários antes de declarações	GO ciano #00add8
.java	Java	JSDoc / Javadoc	JAVA marrom #b07219
.kt, .kts	Kotlin	JSDoc / KDoc	KOTLIN roxo #a97bff
.swift	Swift	JSDoc	SWIFT laranja #f05138
.cs	C#	Doxygen-style (sintaxe XML: <summary>, <param>)	CSHARP verde #178600
.cpp, .cc, .cxx, .hpp, .h	C++	Doxygen (@param, \brief, @returns)	CPP rosa #f34b7d
.c	C	Doxygen	C cinza #555555
.rb, .rake	Ruby	RDoc/YARD (@param, @return, @raise)	RUBY vermelho #cc342d
.lua	Lua	LDoc (---, @tparam, @treturn)	LUA azul marinho #000080
.sql	SQL	Comentários -- estilo dash	SQL (cor padrão jsdoc)
.sh, .bash, .zsh	Shell	Comentários # estilo hash	SHELL (cor padrão jsdoc)
.yml, .yaml	YAML	Comentários # estilo hash	YAML (cor padrão jsdoc)
.html, .htm	HTML	Comentários <!-- -->	HTML (cor padrão jsdoc)
.css	CSS	JSDoc-style em /* */	CSS (cor padrão jsdoc)
.scss, .sass	SCSS	JSDoc-style em /* */	SCSS (cor padrão jsdoc)
.js, .mjs, .cjs	JavaScript	JSDoc / TSDoc	JAVASCRIPT amarelo #f7df1e
.ts, .tsx, .d.ts	TypeScript	JSDoc / TSDoc	TYPESCRIPT azul #3178c6
.jsx	JSX	JSDoc	JSX (cor padrão jsdoc)
.php	PHP	JSDoc	PHP lilás #4f5d95
.dart	Dart	JSDoc	DART ciano #00b4ab
.ex, .exs	Elixir	Python-style docstrings (""")	ELIXIR roxo #6e4a7e
.r, .R	R	Roxygen2 (#')	R azul #198ce7
.jl	Julia	Python-style docstrings (""")	JULIA roxo #a270ba
.hs, .lhs	Haskell	Comentários -- estilo dash, bloco {- ... -}	HASKELL roxo #5e5086
.toml	TOML	Comentários # estilo hash	TOML (cor padrão jsdoc)
outras extensões	Genérico (fallback)	JSDoc	Doc lilás #cba6f7 (cor padrão)

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():
    ...

Anotação	Descrição
@kdocs:since <versão>	Versão em que o símbolo foi introduzido
@kdocs:author <nome>	Autor do símbolo
@kdocs:stability <status>	Texto livre - convenção sugerida: stable, experimental, deprecated
@kdocs:see <referência> / @kdocs:link <referência>	Referência cruzada para outro símbolo ou arquivo
@kdocs:type <nome>	Anota o tipo de uma variável/parâmetro explicitamente
@kdocs:warn <texto>	Aviso destacado no balloon (ex: alertas de uso)
@kdocs:note <texto>	Nota informativa adicional
@kdocs:deprecated <texto>	Marca o símbolo como obsoleto, com o motivo

Modificadores entre colchetes

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

Modificador	Descrição
[!due:YYYY-MM-DD]	Data limite vinculada ao símbolo
[!ticket:ID]	Ticket de issue tracker vinculado
[!low] [!normal] [!high] [!critical]	Nível de prioridade (case-insensitive)
[@nome.de-usuario]	Pessoa responsável/atribuída
[#tag1,tag2]	Tags livres separadas por vírgula

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

Opção	Padrão	Descrição
hover_docs	true	Exibe o balloon ao passar o mouse

---

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.