<div class="page">
<div class="cover text-center">
<img class="mx-auto" src=/itb/images/logo_mislata.png alt="logo">
# Javadoc
<div class="text-end fit-content ms-auto my-3 mt-auto pt-3">
<p><strong>Autor:</strong> Joan Puigcerver Ibáñez</p>
<p><strong>Correu electrònic:</strong> j.puigcerveribanez@edu.gva.es</p>
<p><strong>Curs:</strong> 2024/2025</p>
</div>
<div>
<p class="fw-bold mb-0">Llicència: BY-NC-SA</p>
<p class="d-none d-md-block">(Reconeixement - No Comercial - Compartir Igual)</p>
<a href="https://creativecommons.org/licenses/by-nc-sa/4.0/deed.ca" target="_blank">
<img class="mx-auto" src="/itb/images/license.png" alt="Licence"/>
</a>
</div><!--license-->
</div><!--cover-->
</div><!--page-->
{:toc}
## Documentació
La documentació del codi és un text que acompanya el el codi font
per explicar què fa el vostre codi, per què està escrit tal com és i/o
com utilitzar-lo.
Hi ha dues categories principals de documentació: documentació en el codi
font i documentació de suport sobre el codi.
### Documentació de suport
Un exemple bàsic de documentació de suport és un bon
fitxer __README__. Aquest fitxer hauria d'explicar el propòsit
del software i hauria de proporcionar la informació bàsica i
important sobre el projecte, així com el propòsit, instal·lació,
requeriments, ...
En els projectes allotjats a [GitHub](https://github.com),
el __README__ és previsualitza per defecte al entrar a la
pàgina principal de qualsevol repositori.
::: example
__README__ de __vscode__: https://github.com/microsoft/vscode
:::
La documentació també també es pot proporcionar en forma de
documentació d'API. A aquesta documentació ens referim a
les diferents classes que hi ha i els seus mètodes o les accions
d'una REST API.
::: example
- Documentació oficial de Java: https://docs.oracle.com/javase/7/docs/api/java/lang/String.html
- Referència oficial de Javadoc: https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html
- Documentació de REST API de GitHub: https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28
:::
### Documentació en el codi font
A banda de la documentació de suport, també es poden utilitzar
comentaris en el codi font. Aquests comentaris s'utilitzen per
explicar què fa un troç de codi en concret a persones dins
del teu equip de desenvolupament o a tú mateix en un futur.
## Javadoc
__Javadoc__ és composa d'un mecanisme per generar __documentació API__
automàticament a partir de commentaris en el codi font.
::: docs
Referència oficial de Javadoc: https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html
:::
L'estructura dels comentaris de Javadoc s'assembla molt a un comentari
multilina, però la diferència és que hi ha un asterisc addicional al principi:
```java
// Comentari d'una línia
/*
* Comentari
* multi
* línia
*/
/**
* Açò és Javadoc
*/
```
::: info
A partir de __Javadoc 1.4__, els asteriscs a principi de cada línia són opcionals.
:::
__Els comentaris Javadoc es poden especificar a sobre de qualsevol classe,
mètode o atribut en el codi.__
Els comentaris es composen de dues seccions:
- Una descripció del que estem comentant.
- Etiquetes, identificades per `@`, que descriuren aspectes concrets.
### Etiquetes
Les etiquetes existents són les següents.
Cal indicar-les en aquest ordre.
- `@author` (classes and interfaces only, required)
- `@version` (classes and interfaces only, required. See [footnote 1](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#footnote1))
- `@param` (methods and constructors only)
- `@return` (methods only)
- `@exception` (`@throws` is a synonym added in Javadoc 1.2)
- `@see`
- `@since`
- `@serial` (or `@serialField` or `@serialData`)
- `@deprecated` (see [How and When To Deprecate APIs](https://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/deprecation/deprecation.html))
::: docs
- Documentació sobre les etiquetes: https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#tagcomments
- `@see` vs `@link`: https://www.baeldung.com/javadoc-see-vs-link
:::
### Javadoc en classes
```java
/**
* This class represents a Rectangle
*
* @author Joan Puigcerver
* @version 1.2
*/
public class Rectangle {
// fields and methods
}
```
### Javadoc en atributs
La documentació dees atributs `private` no es generarà
a no ser que explicitament indicem l'opció `-private` a
el generador de Javadoc.
```java
public class Rectangle {
/**
* Width of the rectangle
*/
private int width;
/**
* Height of the rectangle
*/
private int height;
/**
* Position of the Rectangle in the x axis.
*/
private int x;
/**
* Position of the Rectangle in the y axis.
*/
private int y;
}
```
### Javadoc en mètodes
```java
public class Rectangle {
/**
* Computes the area of the rectangle.
*
* @return area of the rectangle
*/
public int area(){
return this.width * this.height;
}
/**
* Checks if the Rectangle contains the point at the specified location (x, y)
*
* @param x the specified X coordinate.
* @param y the specified Y coordinate.
* @return true if the point (x, y) is inside the Rectangle; false otherwise.
* @since 1.2
*/
public boolean contains(int x, int y){
boolean inXRange = (x >= this.x) && (x <= this.x + width);
boolean inYRange = (y >= this.y) && (y <= this.y + height);
return inXRange && inYRange;
}
}
```
## Generació Javadoc
La generació d ela documentació __API__ de Javadoc és realitza mitjançant l'ordre `javadoc`.
No obstant això, els IDEs modern integren opcions per generar aquesta documentació mitjançant
l'interfície gràfica. A __IntelliJ__, la documentació pot ser generada a __Tools > Generate JavaDoc...__.
Aquesta opció obrirà un diàleg que permet triar les opcions de la generació:
{.center}
- __Scope__: Es pot triar els fitxers dels quals es vol realitzar la documentació.
- __Output directory__: Directori on es generarà la documentació. La carpeta especificada ha d'existir d'avant mà.
- __Visibility level__: Nivell de visibilitat dels elements els quals es generarà la documentació.
- _Exemple_: Si s'específica visiblitat `public`, no es generarà la documentació dels elements `protected` ni `private`.
Es pot decidir incloure els fitxers de test a la documentació marcant la casella __Include test sources__.
No obstant això, la generació de la documentació fallarà, ja que l'eina `javadoc` no coneix JUnit i les seues
anotacions. Per poder generar la documentació de test, s'ha d'incloure el plugin `maven-javadoc-plugin` al fitxer
__pom.xml__.
```xml
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.6.3</version>
</plugin>
</plugins>
</build>
...
</project>
```
## Bibliografia
- https://www.oracle.com/es/technical-resources/articles/java/javadoc-tool.html
- https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html
- https://www.baeldung.com/javadoc
- https://blog.submain.com/code-documentation-the-complete-beginners-guide/
- https://textexpander.com/blog/code-documentation
Aquest lloc web utilitza galetes per millorar l'experiència de l'usuari