If you write a comment on the code, you can immediately see what the process is written. If you write javadoc, you can see the comment even if you refer to it. You can understand what kind of processing it is with just javadoc and use it </ b>.
On the contrary, if you write javadoc properly I can't figure out what the class or method does, and I have to go to decipher the code one by one. It ’s simply inefficient.
In the current situation where it is natural for multiple people to develop, someone other than yourself It's natural to use what you make In other words, write with a compassionate heart.
It's required for class and public methods What is private or protected, maybe I don't need to use it in a remote place? Is it like If it's easy to understand in the end, it's okay
If you write too much, it will be hard to see. I don't know what to do if there are few
What should I refer to
It ’s official, right?
Everyone loves System.out.println, familiar with System class
System.java
/**
* The <code>System</code> class contains several useful class fields
* and methods. It cannot be instantiated.
*
* <p>Among the facilities provided by the <code>System</code> class
* are standard input, standard output, and error output streams;
* access to externally defined properties and environment
* variables; a means of loading files and libraries; and a utility
* method for quickly copying a portion of an array.
*
* @author unascribed
* @since JDK1.0
*/
public final class System {
Here's how it actually looks
java.lang.System
The System class has useful class fields and methods. It cannot be instantiated.
The functionality provided by the System class includes standard input, standard output, and error output streams, and externally defined properties.
And how to access environment variables, how to load files and libraries, and utility methods to quickly copy parts of an array
I will.
Introduced version:
JDK1.0
Because it is a class explanation
I think what you want to pay attention to is the \
tag for paragraph division and the \ tag when writing code.
Writing in HTML makes it very easy to see.
The code tag could be {@code null} or {@linkplain method name display text}
You may be able to fly to the reference destination
<ul>
<li>
</ul>
If you edit while watching when javadoc is firmly referenced, such as bullet points in
The directly written javadoc will be a little longer, but the explanation in the reference will be much easier to see!
The method is
System.java
/**
* Reassigns the "standard" output stream.
*
* <p>First, if there is a security manager, its <code>checkPermission</code>
* method is called with a <code>RuntimePermission("setIO")</code> permission
* to see if it's ok to reassign the "standard" output stream.
*
* @param out the new standard output stream
*
* @throws SecurityException
* if a security manager exists and its
* <code>checkPermission</code> method doesn't allow
* reassigning of the standard output stream.
*
* @see SecurityManager#checkPermission
* @see java.lang.RuntimePermission
*
* @since JDK1.1
*/
public static void setOut(PrintStream out) {
checkIO();
setOut0(out);
}
The actual appearance is
void java.lang.System.setOut(PrintStream out)
setOut
public static void setOut(PrintStream out)
Reassign the "standard" output stream.
RuntimePermission to see if the standard output stream, if present, can be reassigned("setIO")The checkPermission method is called with permissions.
Parameters:
out -New standard output stream
exception:
SecurityException -If a security manager exists and its checkPermission method does not allow the standard output stream to be reassigned.
Introduced version:
JDK1.1
Related item:
SecurityManager.checkPermission(java.security.Permission), RuntimePermission
So, after all
@param
Arguments (not only out out or translated, but also information about what arguments will be included)
@ return
Return value (concrete and concise what will be returned without roughening the acquisition result)
@ throws
exception (simply explain when it happens)
See @see
@since
introduction version
Etc. seems to be important
What seems important in the documentation is
It's not good to write too much, as it is useless to have a million lines of explanation for a person who is not a big deal Moderately easy to understand, simple and clear It's really itchy ...
In the first place, if the name is correct, you can generally understand what it will do, and if you have javadoc, it will be perfect. Naming and javadoc are important, right?
So I decided to write javadoc firmly