Ao desenvolver uma aplicação, pode ser muito útil ter acesso rápido aos detalhes de um método(por exemplo, uma explicação do que faz, a sua sintaxe, e uma definição dos parâmetros que lhe são transmitidos). Isto torna-se ainda mais importante quando se utiliza um componente compilado. Não se pode olhar para o conteúdo do método, pelo que só se pode confiar na sua documentação para compreender como utilizá-lo.
O diálogo do Explorer foi melhorado e a documentação está agora disponível em 4D v18 R3 para bases de dados de projectos.
A documentação é guardada num ficheiro com o mesmo nome que o método ou forma numa pasta de documentação. O novo formato para a documentação é Markdown.
Porquê o “Markdown”?
A linguagem Markdown permite-lhe formatar texto e tem uma sintaxe muito simples. Assim, o documento é fácil de ler e escrever, sem interromper a sua interpretação.
Muitas ferramentas utilizam o Markdown para formatar a documentação. Por exemplo, GitHub fornece um intérprete Markdown integrado.
Documentação em 4D
A documentação está disponível para:
- Métodos de projecto
- Métodos de base de dados
- Métodos de disparo
- Métodos de formulário de projecto
- Métodos do formulário de tabela
- Aulas
Quando exporta a sua base de dados binária como um projecto, a sua documentação existente é guardada em ficheiros em formato Markdown.
Para criar ou editar o ficheiro de documentação numa base de dados de projectos, clique no botão “Criar” ou seleccione o item de menu “Editar Documentação” no Explorador.
4D cria o ficheiro correspondente e abre-o no seu editor predefinido. O ficheiro inclui um modelo:
<!-- Type your summary here --> ## Description ## Example ```4d Type your example here ```
Pode ver que a primeira linha utiliza as etiquetas de comentários HTML. Esta informação é exibida no editor do método quando se passa o cursor sobre o método. O resto do ficheiro é exibido no separador “Documentação” do explorador.
Exemplo
Se utilizarmos o método getWeekday como exemplo, aqui está o resultado:
Num próximo post no blog, mostrar-lhe-emos como fazer uso de comentários para escrever a sua própria documentação para componentes. Fique atento!