/advpl-doc

Gera header Protheus.doc automatico em todas as funcoes do fonte. Infere tipo de parametro pelo prefixo (c_=Char, n_=Num, etc). Cria .bak.

Assinatura: /advpl-doc <arquivo.prw> [--dry-run] [--force]

/advpl-doc resolve um problema clássico: fonte legado sem documentacao. Le o arquivo, identifica todas as funcoes (User Function, Function, Static Function), extrai parametros, infere tipos, e gera bloco /*/{Protheus.doc}/*/ antes de cada uma.

Como usa

# Roda em 1 arquivo
/advpl-doc C:\fontes\rotina-legada.prw

# Preview sem escrever (so mostra o que seria gerado)
/advpl-doc rotina.prw --dry-run

# Sobrescrever mesmo se ja tiver header
/advpl-doc rotina.prw --force

# Pasta inteira recursiva
/advpl-doc ./src/customizacoes/

Inferencia de tipo por prefixo

Prefixo	Tipo Protheus.doc
`c_`	Character
`n_`	Numeric
`l_`	Logical
`d_`	Date
`a_`	Array
`o_`	Object
`b_`	CodeBlock
outros	tag `@param` sem tipo (admite incerteza)

Exemplo: antes/depois

// ANTES
User Function CalcDesc(nValor, cClasse, lVIP)
    Local nDesc := 0
    If lVIP
        nDesc := nValor * 0.15
    EndIf
Return nDesc

// DEPOIS (skill adiciona o header)
/*/{Protheus.doc} CalcDesc
Calcula desconto baseado em valor, classe e flag VIP.

@type   Function
@author claude-advpl-skill (auto-generated)
@since  13/05/2026
@param  nValor,  Numeric,  Valor base
@param  cClasse, Character, Classe do cliente
@param  lVIP,    Logical,  Se cliente e VIP
@return Numeric, Valor do desconto calculado
/*/
User Function CalcDesc(nValor, cClasse, lVIP)
    Local nDesc := 0
    If lVIP
        nDesc := nValor * 0.15
    EndIf
Return nDesc

Backup automatico

Antes de modificar, cria rotina.prw.bak. Se algo der errado, e so renomear de volta.

Quando NAO sobrescrever

Se a funcao ja tem /*/{Protheus.doc}, skill nao mexe — protege documentacao manual. Use --force pra ignorar isso.

Casos de uso

Codigo legado herdado sem doc
Refatorar User Function antiga e gerar doc na hora
Auditoria — todos fontes do projeto com doc minimo (mesmo se generico)
Padronizacao em monorepo de cliente

Limitacoes honestas

Descricao "Calcula X" e inferida do nome da funcao — pode ficar generica
Tipo inferido por prefixo eh convencao, nao garantia. Variavel sem prefixo (ex: codigo) sai sem tipo.
Funcoes em macro (&cMacro) podem nao ser detectadas
Sempre revisar o doc gerado antes de commitar

Instalacao

A skill faz parte do pacote claude-advpl-skill open source. Baixe e instale:

curl -O https://archtecgroup.com.br/downloads/claude-advpl-skill-v0.2.1.zip
unzip claude-advpl-skill-v0.2.1.zip
bash install.sh
# OU Windows PowerShell:
.\install.ps1

Documentacao tecnica completa: GitHub maycondev/claude-advpl-skill

Caso de uso real (post): Auditando 800 linhas de AdvPL em 30 segundos

Suporte / Customizacao

Precisa adaptar a skill pro seu fluxo, integrar em pipeline CI/CD custom, ou usar em ambiente corporativo com NDA?

A ArchTec oferece consultoria especializada em automacao de dev Protheus com Claude/AI. Fale com nossos especialistas →