Let's write Javadoc

Importance of javadoc

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.

Where to write

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

In other words, what to write

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

  • What is the class doing?
  • Clarified that instance is not possible
  • What kind of methods are there as a whole?
  • Introduced version
Is listed

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

  • What method to do
  • If it behaves differently depending on the situation
  • (I haven't written it) Is null good for the argument?
  • I wonder if there can be no null in the return value
Wouldn't it be nice if something like that was written?

But that doesn't mean

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

Recommended Posts