Java documentation – @ return and @ param

I want to know how to use @ return and @ param to record code? I guess I'll do something similar

@return(whatever the method is returning)
@param(parameters that the method is taking in)

Do I need to provide more instructions later? Also, are there too many documents?

Solution

The Javadoc style guide explains the intended use of these tags@ Param describes a parameter and @ return describes the return value (there are other useful labels.)

Remember, Javadoc generates documentation from your code, not just your comments The signature of the method will appear in the output - so don't tell the reader what he already knows The purpose of your document is to provide additional semantics not expressed in the signature Is the numeric parameter limited to a specific value range? Is there any special return value (such as null)? Record the contract

You ask if there are too many documents Right here. API reference documents are very useful in telling the reader all the content and what he needs to know when using the interface correctly Therefore, please record the contract completely, but do not explain how the code implements this interface Link to other elements of the API (such as other classes or interfaces) if they directly host the part you are recording (for example, if someone needs to use somefactory to get an instance of something, the class you are recording)

This is not to say that you should never write a few words; Sometimes the interface is very complex and needs more explanation Consider whether the explanation belongs to the top-level document or specific member of the package overview, class or interface If you find yourself cutting and pasting the explanation in several places, it may indicate that you need to deal with it at a higher level