Documentação de Código

## Comentários

- Comentários permitem aos programadores incluírem texto livre no meio de um programa
- Esse texto **não afeta** o comportamento do programa
    - É ignorado pelo compilador ou interpretador
    - Mas pode ser muito útil para facilitar a compreensão do programa por parte de quem lê o código

---

## Comentários em Haskell

- Estão previstos dois tipos de comentário:
    - *single-line*: desde `--` até ao final de linha
    - *multi-line*: entre `{-` e `-}`
- Por exemplo

```haskell
{- "fact n" calcula o factorial de um número inteiro "n".
   obs: assume-se que o argumento "n" é não negativo.
-}
fact :: Integer -> Integer
fact 0 = 1               -- caso base da recursividade
fact n = n * fact (n-1)  -- caso inductivo
```

---

## Boas práticas

- Um comentário é texto livre, mas:
    - Não deve "repetir" o programa por palavras
    - Pode descrever a intenção do código respetivo
    - Pode explicitar as estratégias/algoritmos utilizados na resolução de um problema
- É habitual usar comentários temporários para:
    - Descrever funcionalidades a ser implementadas ou pontos que merecem atenção (`FIXME`,`TODO`)
    - Excluir código que se destine a teste ou debugging

---

## Comentários Estruturados

- Adicionar informação ao código desenvolvido
    - Comentários seguem uma estrutura própria
        - Permitir a extração automática de documentação
- Documentação sempre atualizada face ao código
- Sistema de documentação pode referenciar código
- Exemplo = documentação das [bibliotecas Haskell](http://www.haskell.org/ghc/docs/latest/html/libraries/index.html)
    - Para consulta no [Hoogle](https://hoogle.haskell.org/)

---

## Comentários Estruturados em Haskell

- `haddock` é uma ferramenta de extração de documentação para programas Haskell
- Processa programas com anotações nos comentários
- Produz como resultado HTML com documentação
- Mais detalhes na [documentação do haddock](http://www.haskell.org/haddock/doc/html/)

---

## Funcionalidades Haddock
 
- Comentário referente à **declaração que se segue** (e.g. funções, tipos,
  construtores)
    - Blocos: entre `{-` e `-}`
    - Linhas: `--` em cada linha

```haskell
{- | A função 'fact' calcula o factorial 
      (@fact n@ retorna o factorial
      de de um inteiro @n@).
-}

-- | A função 'fact' calcula o factorial 
--   (@fact n@ retorna o factorial
--   de de um inteiro @n@).
```

---

## Funcionalidades Haddock
 
- Comentário referente ao **item imediatamente anterior** (e.g. tipo envolvido numa assinatura)
    - Iniciado por `-- ^`

```haskell
fact :: Int -- ^ argumento 'n' (assume-se não negativo)
     -> Int -- ^ resultado
```

---

## Formatação Haddock
  
- Utilizar marcas para formatação do texto, como:
    - Parágrafos são separados por linhas em branco
    - Imprime `text` em itálico (`/text/`), bold (`__text__`) ou mono-espaçamento (`@text@`)
    - Hiper-ligação para `name` (`'name'`)
    - Item de uma lista (`* item`)
    - Item de uma enumeração (`1. item`)
    - Secções: `= heading`, `== subheading`, `=== subsubheading`
  
---
  
## Formatação Haddock
  
- Código em bloco (entre `@`) ou linha única (`>`)
- Exemplos de utilização (`>>>`)
        - Resultado esperado na linha seguinte

```haskell
@
     fact n = if n>0
              then n*fact (n-1)
              else 1
@
> fact n = if n>0 then n*fact (n-1) else 1

>>> fact 5
120
```

---

## Invocação do Haddock
  
```bash
haddock -h -o doc/html Main.hs
```

- Gerar documentação para o ficheiro Haskell `Main.hs`
    - Também podia ser para uma diretoria
- `-h` indica que se pretende que a documentação seja produzida no formato HTML
- `-o doc/html` indica que os ficheiros resultantes devem ser gravados na diretoria `doc/html`
- Documentação gerada na página `doc/html/index.html`

---

## Exemplo Haddock

```haskell
{-|
Module      : Exemplo
Description : Módulo Haskell contendo funções recursivas.
Copyright   : (c) Alguém <alguem@algures.com>, 2024
              Outro  Alguém  <outro@algures.com>, 2024
Maintainer  : alguem@algures.com
Stability   : experimental
Portability : POSIX
Este módulo contém definições Haskell para o cálculo de funções recursivas simples (obs: isto é apenas uma descrição
-}
module Exemplo where
{-| A função 'fact' calcula o factorial (@fact n@ retorna o factorial de um inteiro @n@).
Alternativamente a função poderia ser definida da seguinte forma:

@
fact n = if n>0 then n * fact (n-1)
else 1
@

==  __Exemplos de utilização:__

>>> fact 5
120
>>> fact 0
1

== __Propriedades:__

prop> fact 0 = 1
prop> n>0 => fact n = n * fact (n-1)

-}
fact ::
  Integer       -- ^ argumento assume-se não negativo
  -> Integer    -- ^ resultado
fact 0 = 1
fact n = n * fact (n-1)
{-| A função 'fib' retorna o @n@-ésimo elemento da sequência de Fibonacci.
Algumas características que distinguem a função 'fib' da 'fact':

* o padrão de recursividade é binário;
* dispõe de dois casos base.

== __Exemplos de utilização:__

>>> fib 4
3
>>> fib 10
55
-}
fib :: Integer -> Integer
fib 0 = 0
fib 1 = 1
fib n = fib (n-1) + fib (n-2)
```