class: center, middle, inverse
# Documentació del codi - KDoc i Dokka
---
# Documentació
La millor documentació és un codi que s'expliqui per si mateix
- nom de variables, funcions, classes...
- organització dels fitxers, directoris, packages...

També cal coneixer altres tecniques per generar documentació adicional al codi: 
**KDoc**, similar a JavaDoc

---
# KDoc
## Caracteristiques de la documentació
Es genera en el propi codi, de forma similar als comentaris de bloc

Peculiaritats:
- Doble asterisc a l'inici del bloc
- Un asterisc a cada linia de comentari
```
 /**
  *
  */
```

---
# Contingut del KDoc

## Descripció de l'element (funció, class...)
En el primer paràgraf -> descripció del element que documentem
```
 /**
 * Prints the options
 */
 fun printOptions(){
    println(getOptions())
 }
```
```
 /**
 * Data class to hold user info
 */
 data class User(val id: String, val name: String){
 }
```

---
# Contingut del KDoc 
## Etiqueta *@param*
Després de la descipció, podem indicar quins són els parametres d'entrada:
- @param name description.

```
/*
 * @param url an absolute URL giving the base location of the file.
 * @param name the name of the file.
 */
fun getFile(path: URL, name: String){
    //TODO
}
```
---
# Contingut del KDoc 
## Etiqueta *@param*
Equivalent:
 - @param[name] description.

```
/*
 * @param[url] an absolute URL giving the base location of the file.
 * @param[name] the name of the file.
 */
fun getFile(path: URL, name: String){
    //TODO
}
```
---
# Contingut del KDoc 
## Etiqueta *@return*
Descripció del resultat

```
/*
 * @return a List of with the diferent options as Strings
 */
fun getOptions(): List<String>{
    options = mutableListOf<String>()
    //TODO: fill the option list

return options 
}
```
---
# Contingut del KDoc 
## Altres etiquetes (tags):
 - **@author** Alumn name -> Specifies the author of the element being documented.
 - **@see** otherClass -> Adds a link to the specified class or method to the See also block of the documentation.
 - **@sinse** 1.0.1 -> Specifies the version of the software in which the element was introduced. 
 - ...

Podem posar varies etiquetes @author i @see
---

# Dokka - Documentació en Html
Tots els comentaris de documentació es poden passar a format web

Per fer-ho utilitzarem el pluguin Dokka (_build.gradle.kts_)
```
plugins {
    id("org.jetbrains.dokka") version "1.6.10"
}
```

.full_width[![](img/dokka-intellij.png)]

---
# Dokka - Documentació en Html
Executem l'opció **DokkaHtml**
.full_width[![](img/dokka2html.png)]

---
# Exemple:
Se'ns ha generat el codi dins de la carpeta build > dokka on hi tenim la documentació en format html.

- [codi](https://gitlab.com/marcvives/schoolmanager/-/tree/master/src/main/kotlin/cat/itb/schoolmanager)
- [html](https://marcvives.gitlab.io/schoolmanager/dokka)

---
# Referències:

## https://kotlinlang.org/docs/kotlin-doc.html

## https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html