Documentar seu código com o XML (Visual Basic)

  • Artigo

No Visual Basic, você pode documentar seu código usando XML.

Comentários da documentação XML

O Visual Basic fornece uma maneira fácil de criar automaticamente a documentação XML para projetos. Você pode gerar automaticamente um esqueleto XML para seus tipos e membros e, em seguida, fornecer resumos, documentação descritiva para cada parâmetro e outras observações. Com a configuração apropriada, a documentação XML é emitida automaticamente em um arquivo XML com o mesmo nome de arquivo raiz do projeto. Para obter informações sobre como configurar a geração do arquivo de documentação XML, consulte a opção do compilador -doc e a propriedade GenerateDocumentationFile MSBuild.

O arquivo XML pode ser consumido ou manipulado como XML. Esse arquivo está localizado no mesmo diretório que o arquivo de saída .exe ou .dll do projeto.

A documentação XML começa com '''. O processamento desses comentários tem algumas restrições:

  • A documentação deve ser em XML bem formado. Se o XML não estiver bem formado, um aviso será gerado e o arquivo de documentação conterá um comentário dizendo que foi encontrado um erro.

  • Os desenvolvedores são livres para criar seu próprio conjunto de marcas. Há um conjunto recomendado de marcas (consulte Marcas de Comentário XML). Algumas das marcas recomendadas têm significado especial:

    • A marca <param> é usada para descrever parâmetros. Se ela for usada, o compilador verificará se o parâmetro existe e se todos os parâmetros são descritos na documentação. Se a verificação falha, o compilador emite um aviso.

    • O atributo cref pode ser anexado a qualquer marca para fornecer uma referência a um elemento de código. O compilador verifica se esse elemento de código existe. Se a verificação falha, o compilador emite um aviso. O compilador respeita qualquer instrução Imports quando procura por um tipo descrito no atributo cref.

    • A marca <summary> é usada pelo IntelliSense no Visual Studio para exibir informações adicionais sobre um tipo ou membro.

Para obter detalhes sobre como criar um arquivo XML com comentários da documentação, confira os tópicos a seguir:

Confira também