# Javadoc

Hello!
In this article, i will discuss javadocs as well as some tips on writing javadocs.

### JavaDocs
Javadoc is a documentation generation system, which reads comments in the source and generates compiled documentation in the form of HTML5.

### Why use javadocs?

* Improved understanding of the general structure of the project
* help coworkers understand the complicated code
* easy to generate 

### How to write a javadocs
With the help of Intellij, you could easily just type /** and press enter:


```
/**
``` 

Intellij just auto-generates the javadocs comments like this:


```
    /**
     * 
     *
     *  
     */
``` 

If you have a return type, parameters, and throw exceptions, IntelliJ also auto-generates for you.


```
    /**
     * Returns a newly generated id
     * @param a
     * @return a generated id
     * @throws Exception
     */
    public Long example(Long a) throws Exception {
        newId += 1;
        return newId;
    }
``` 
In the beginning, it is best to describe what the method returns. You could understand a lot if you understand what returns. 

This method is fairly simple, but imagine a complicated, legacy method in which there are many parameters and returns unreadable numbers. It will save a lot of time for developers if you have a javadocs that explains what the method does and returns. 

###  advice for writing javadocs

* The goal is to understand the code within a few seconds
* The javadocs class must explain the goal and responsibilities
* The javadocs method must explain parameters and what it returns
  - do not include explanations for implementations
  - briefly explain what exception is thrown 
* Try to avoid any comments inside the code


### Conclusion
In this post, i included what a javadocs is and some tips on writing javadocs.

### Reference
* https://johngrib.github.io/wiki/java/javadoc/#standard-tags
* https://www.oracle.com/ca-en/technical-resources/articles/java/javadoc-tool.html