I am currently taking an AP Java class and I can't even begin to understand what "javadoc" is whatsoever, all that I seem to take out so far is that its a "different" way of commenting when creating an API so a programmer can better read the code . . .
I am new to this and I would appreciate any beginning point so I can at least grab on to the concept.
55 Answers
I was thinking about how to describe it, but honestly I think the SO Javadoc tag does a very good job:
Javadoc is an extensible documentation generation system which reads specially formatted comments in Java source code and generates compiled documentation. It is typically used to produce API documentation in the form of HTML web pages.
Many IDEs also make use of Javadocs to generate contextual API descriptions. Javadocs can make the difference between an extremely obscure library and something that is a delight to use.
Javadocs, use them!!
8Whenever you need to look up a Java method, you Google the name of the method and refer to the docs to see what it does. Great !
But how did these docs come in place ? How was so much documentation generated ? Was someone hired to do that ?
Well, whenever you write code you need to properly explain it in the source files using comments. /** */ marks a comment block. Now, javadoc is responsible for parsing these comments into documentation (It makes HTML files out of these comments). So, nobody was hired just javadoc was executed.
Here is an example of beginning comment:
/**
* Classname
* Version info
* Copyright notice
*/But that is not all. javadoc is very powerful. It allows you to even write basic HTML inside the comments and then it parses the HTML to come up with a proper output. /** <html> */ That is why some JacaDoc pages have tables. These were made using the <td> and <tr> tags in HTML
For example,
/** * First paragraph. * <p><ul> * <li>the first item * <li>the second item * <li>the third item * <ul><p> * Second paragraph. */If you want javadoc to work properly with your code, follow the Java Code Convention : if your code adheres to the convention, it becomes easy for javadoc to make the documentation.
Here is the official Oracle guide to writing documentation comments:
2Javadoc is a program that reads your java files and creates HTML documentation out of them. You use it by adding comments with documentation, then invoking it.
Javadoc is a program much like a compiler that reads your codes and plucks out certain parts of it in order to create a (very very very very very) useful documentation in the form of html pages. The API pages you use for standard java code is made using Javadoc.
While parsing your code, Javadocs looks for two things: code structure and Javadoc comments. The code structure is just the code itself. That is used to build up the basic structure of a page (ie class name, fields, methods, etc). Javadoc comments are special comments that start with /** instead of the usual /* As far as the regular java compiler is concerned, it makes no difference though. Once in a Javadoc comment you write about the specific aspect of the code you are referencing and are able to use html tags as well as some other special syntax. You can learn more about it here
Sun defines JavaDoc as follows ():
Javadoc is a tool for generating API documentation in HTML format
from doc comments in source code The comments have a certain format that has become widely known as "Javadoc". You can see more details at
