Bases de dados de projectos: A documentação do método está de volta

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!