Java Javadoc
Document a method with a special comment so readers and tools can see what it takes and what it returns. In Yard.java, write a method add that takes int x and int y and returns their sum. Place a /** */ block directly above add. Inside that block, describe the work in one short sentence, then tag each parameter with @param and the result with @return. In main, print add(10, 2). Compile with javac Yard.java and run java Yard. The screen should show 12. Leave naming rules for the next page — this lesson is the documentation comment shape, not choosing names.
Place /** above the method
The debugging page printed values to find a wrong sum. This page writes a documentation comment above a clean method. Open Yard.java. Keep the public class name Yard. Delete leftover println debug labels that bury the documentation story, leftover equals / == demos, leftover Machine horn files, and any keyboard Scanner. The program must not wait for typing. No import line is required for this demo.
Inside Yard, keep a small method and a short main. The documentation block must sit immediately above the method it describes. A blank line between the closing */ and the method line is fine. Do not hide the block inside main. Do not put the block under the method body.
Write the opening of the comment with two stars after the slash:
/**
Then write one plain sentence that says what add does. Then write the tags. Close with:
*/
The method itself stays ordinary Java:
static int add(int x, int y) {
return x + y;
}
Javadoc does not change how return works. It tells a reader what the method promises before they read every line of the body.
public class Yard {
/**
* Adds two numbers.
* @param x first number
* @param y second number
* @return the sum of x and y
*/
static int add(int x, int y) {
return x + y;
}
public static void main(String[] args) {
System.out.println(add(10, 2));
}
}
From the folder that holds Yard.java, run javac Yard.java. When parentheses, braces, and semicolons match, javac writes no line of its own. Then run java Yard — not java Yard.java. Leave the .java ending off the run command. Keep one public class in the file so the name matches Yard.
The screen shows 12. Walk the run once. Java starts at Yard.main. The call add(10, 2) enters the method with x holding ten and y holding two. The return line hands back twelve. System.out.println writes that number. The Javadoc block does not print on its own. The block is for readers and documentation tools. The beginner proof on this page is still a correct run after a clear comment.
Read the comment block while you look at the method signature. The sentence Adds two numbers. matches the work of return x + y;. The line @param x first number names the first parameter. The line @param y second number names the second parameter. The line @return the sum of x and y names the result. Keep the tag spelling exact: @param and @return use the @ sign and Latin letters.
If you still see x=10 and y=2 then 8 from a debugging file, switch to the Javadoc teaching file and run java Yard again. If you only write // Adds two numbers. above the method, you wrote an ordinary line comment, not a Javadoc block. Keep the double-star form /** so the block is documentation, not a single-line note.
Say the rule out loud while you watch the screen: document above the method, tag the parameters, tag the return, then compile and run to prove the method still works. Do not invent long naming lectures on this page. Naming waits for the next lesson.
Read the tag map
A short table keeps the three pieces you typed in the comment. The opening /** */ marks a documentation block. @param describes one parameter name. @return describes the value the method hands back. Keep the method name add and the call add(10, 2) so the screen stays a single clear number.
The table is the short map of this page. First you place the block. Then you tag inputs and output. Then you verify with javac and java Yard. Skip guessing that any comment style is Javadoc. Skip deleting the block before you know the program still prints 12.
📊 Beginner Javadoc pieces on Yard
| Piece | What it does |
|---|---|
/** */ |
Marks a documentation comment above a method |
@param |
Describes one parameter by name |
@return |
Describes the value the method returns |
Keep the table beside the teaching file while you edit. Point at @param x in the file, then at int x in the signature. Point at @param y, then at int y. Point at @return, then at the return line. That matching game is the whole beginner idea in one pass. Tools that read Javadoc look for those tags. Human readers use the same map when the method body grows later.
If leftover debugging demos still sit nearby, keep them as history. For this lesson run the Javadoc teaching file so the screen shows 12 from add, not labeled x= lines from a hunt. If javac complains about duplicate public classes, keep only Yard public.
Ordinary // is not Javadoc
A line that starts with // is a note for someone reading the file. It is useful, and this course already used line comments earlier. It is not the documentation block shape this page teaches. Javadoc for a method starts with /** and ends with */. The @param and @return tags sit inside that block.
If you place a plain string under the method after other statements, that string is not method documentation. The documentation block must be the comment attached above the method. Keep the block tight to add. Keep main free of fake documentation theater. The call in main stays a normal print of the returned sum.
When the comment is wrong but the method body is right, javac can still succeed and java Yard can still print 12. That is why this page asks you to read the comment and the signature together, not only the screen. The screen proves the math. The comment proves you labeled the contract.
Compared with debugging prints
On the debugging page, println answered what your numbers really were when a sum looked wrong. On this page, Javadoc answers what add promises before a reader digs into the body. You still compile Yard.java and run java Yard. The new tokens are /**, @param, and @return above a method.
Debugging used ordinary output as a flashlight. Javadoc uses a structured comment as a label on the method door. When the label matches the parameters and the return, readers waste less time guessing. When the label is missing, the program can still run — the documentation habit is still missing.
If a leftover debugging file is still open, you may see x=10, y=2, and an old sum. Switch to the Javadoc file so main prints add(10, 2) and the method carries the documentation block. Keep naming style lectures off this page. Keep keyboard input off this page.
Before naming
You can place /** */ above add, tag @param x, tag @param y, tag @return, and still see 12 after java Yard. Compile Yard.java and run java Yard for the kept demo. The comment told readers the contract. The next page is naming, where you choose clear names for what you write.
Keep the documented add demo for a clear comment-plus-run pair. Keep debugging files off this page when you practice documentation. Keep naming files off this page until that lesson. Those three habits are the checkpoint before you move on. When the tags match the signature and the screen shows 12, Javadoc did its job for this lesson and you are ready for the next topic about naming.
One last pass through the folder: one public Yard, one documented add, one print in main, no keyboard wait, no forced naming rules. Run javac Yard.java and java Yard once more on the demo you keep open. If the screen still shows 12 and the comment still sits above add with @param and @return, the documentation shape is solid and the course can move to naming on the next page. Prefer one clear documentation block on one method so each read teaches the same map.
🧠 Test Your Knowledge
Test Your Knowledge
Challenge yourself with this interactive quiz and see how well you understand the topic
📝 Instructions
- Read each question carefully
- Select the best answer for each question
- You can retake the quiz as many times as you want
- Your progress will be shown at the top