آموزش جاوا - مستندسازی

زبان جاوا سه نوع نظر (comment) را پشتیبانی می‌کند:

این فصل درباره توضیح Javadoc است. خواهیم دید چگونه می‌توانیم از Javadoc برای تولید مستندات مفید برای کد جاوا استفاده کنیم.

چیستی Javadoc؟

Javadoc ابزاری است که با JDK همراه است و برای تولید مستندات کد جاوا به فرمت HTML از کد منبع جاوا استفاده می‌شود و نیاز به مستندسازی به فرمت مشخصی دارد.

مثال ساده‌ای را می‌توانید در زیر مشاهده کنید که خطوط داخل /*...*/ نظرات چندخطی جاوا هستند. به طور مشابه، خطی که به // پیش می‌آید، یک نظر یک خطی جاوا است.

مثال

/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

شما می‌توانید برچسب‌های HTML مورد نیاز را در قسمت توضیحات قرار دهید. به عنوان مثال، مثال زیر از <h1>...</h1> برای عنوان و از <p> برای ایجاد شکست پاراگراف استفاده کرده است −

مثال

/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
* 
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

برچسب‌های javadoc

ابزار javadoc از برچسب‌های زیر پشتیبانی می‌کند −

مثال

برنامه زیر از چندین برچسب مهم موجود برای نظرات مستند استفاده می‌کند. می‌توانید بر اساس نیازهای خود از سایر برچسب‌ها استفاده کنید.

مستندات درباره کلاس AddNum در فایل HTML به نام AddNum.html تولید می‌شود اما در عین حال یک فایل اصلی با نام index.html نیز ایجاد خواهد شد.

import java.io.*;

/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31
*/
public class AddNum {
   /**
   * This method is used to add two integers. This is
   * a the simplest form of a class method, just to
   * show the usage of various javadoc Tags.
   * @param numA This is the first paramter to addNum method
   * @param numB  This is the second parameter to addNum method
   * @return int This returns sum of numA and numB.
   */
   public int addNum(int numA, int numB) {
      return numA + numB;
   }

   /**
   * This is the main method which makes use of addNum method.
   * @param args Unused.
   * @return Nothing.
   * @exception IOException On input error.
   * @see IOException
   */

   public static void main(String args[]) throws IOException {
      AddNum obj = new AddNum();
      int sum = obj.addNum(10, 20);

      System.out.println("Sum of 10 and 20 is :" + sum);
   }
}

حالا، فایل AddNum.java بالا را با استفاده از ابزار javadoc به صورت زیر پردازش کنید:

$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
Generating /package-frame.html...
Generating /package-summary.html...
Generating /package-tree.html...
Generating /constant-values.html...
Building index for all the packages and classes...
Generating /overview-tree.html...
Generating /index-all.html...
Generating /deprecated-list.html...
Building index for all classes...
Generating /allclasses-frame.html...
Generating /allclasses-noframe.html...
Generating /index.html...
Generating /help-doc.html...
1 warning
$

شما می‌توانید تمام مستندات تولید شده را در اینجا بررسی کنید - AddNum. اگر از JDK 1.7 استفاده می‌کنید، javadoc یک stylesheet.css عالی تولید نمی‌کند، بنابراین پیشنهاد می‌کنیم از stylesheet استاندارد را از https://docs.oracle.com/javase/7/docs/api/stylesheet.css دانلود و استفاده کنید.