65.9K
CodeProject 正在变化。 阅读更多。
Home

基本 Javadoc 指南

iampeluca
starIconstarIconstarIconstarIcon
emptyStarIcon
starIcon

4.90/5 (9投票s)

2013年9月25日

CPOL

4分钟阅读

viewsIcon

31723

Javadoc 标签的快速参考

引言

本文尝试总结 Javadoc 的基础知识：重要性、基本用法和标签参考，以创建两种现有类型的文档：用法文档和实现文档。

背景

用法文档面向需要了解代码功能以及如何在自己的代码中使用它的用户，但他们实际上不需要知道实现是如何工作的。让我们以任何 API 为例，要在您的代码中使用它，您只需要知道需要发送什么和返回什么，代码如何完成这项工作在这种情况下并不是真正必要的。

实现文档面向需要详细描述每个方法上如何实现功能的用户，这对于维护、增强或调试代码的人员非常有用。

使用这两种类型的文档重要吗？答案是坚定的“是”。这是您应该在代码中实施的最佳实践之一。当您创建代码时，除了您自己，没有人知道它做什么以及应该如何使用它，如果有人需要您的代码，那么快速理解它并不容易，假设您在 3 个月后需要该代码，您可能不会记得它。此外，使用 Javadoc，您可以生成外部文档，这对于作为公共参考非常有用。

Using the Code

什么应该有文档？

好吧，一切都可以有文档，但至少有 3 个需要文档的区域（无论它们是 public、protected 还是 private）

  • 类
  • 常量、变量
  • 方法

以下是执行基本文档的代码、语法和标签参考。

特殊字符

首先，在您的文档中，您应该转义在 HTML 中具有特殊含义的特殊字符，例如 &、< 和 >，在这种情况下

  • 将 & 更改为 &
  • 将 < 更改为 &lt;
  • 将 > 更改为 &gt;

需要转义的其他特殊字符是

  • &reg; (®)
  • &Aacute; (Á)
  • &aacute; (á)
  • &ntilde; (ñ)

请记住，有很多这样的字符，您可以使用这个 表格作为参考。请注意，Javadoc 就像编写 HTML 一样，您可以使用 <a href>、<p>、<br> 等标签。

Javadoc 标签

有用于多种用途的标签，以下是其中一些标签及其使用位置

@author

使用此标签来描述作者。

适用于：类、接口和枚举

示例

/**
 * @author diego
 */
public class MyLittleClass{...}

利用 HTML 标签，您可以使用更详细的内容，例如

/**
 * @author diegohp (Diego Hernandez Perez) - 
 * <a href="mailto:hp.diego@gmail.com">hp.diego@gmail.com</a>
 */
public class MyLittleClass{...}

@version

使用它来提供软件的版本。

适用于：类、接口和枚举

示例

/**
 * @version 1.0
 */
public class MyLittleClass{...}   
/** 
 * @author 5.4.2
 */
public class MyLittleClass{...}

@since

使用它来描述功能的首次出现。

适用于：类、接口、枚举、字段和方法。

示例

/**
 * @since 1.0
 */
public class MyLittleClass{...}   
/**
 * @since 4.3.2
 */
public class MyLittleClass{...}

@see

使用它来引用其他文档元素。

适用于：类、接口、枚举、字段和方法。

示例

引用类或接口

/**
 * @see ArrayList
 */
public class MyLittleClass{...}

引用类或接口的方法（也使用 # 访问类的变量，以及 YourClass#yourMethodOrField 来引用其他类的方法/字段）

/**
 * @see #add(java.lang.Object) 
 */
public void addUsingExtraSteps(Object object, int i){...}

@param

使用它来描述方法的参数。

适用于：方法。

示例

/**
 * @param file       The file that needs to be renamed.
 * @param newName    The the new name of the file.
 */
public void renameFile(File file, String newName){...}

@return

使用它来描述返回值。

适用于：方法。

示例

/**
 * @return   A string with the password encrypted.
 */
public String encrypt(String password){...}

@throws 或 @exception

使用它来描述当前方法可能抛出的异常。

适用于：方法。

/** 
 * @throws FileNotFoundException   If the files doesn't exist.
 */
public File getFile(String path) throws FileNotFoundException {…}

@deprecated

使用它来描述类、字段或方法已过时。

适用于：类、接口、枚举、字段和方法。

示例

/**
 * @deprecated Use {@link #encryptWithMD5(String)} instead.
 */
public String encrypt(String password){...} 
/**
 * @deprecated Use {@link MyNewLittleClass} instead because blablabla.
 */
public class MyLittleClass{...}

{@inheritDoc}

当您想要复制重写方法的描述时使用它。

适用于：重写方法。

/**
 * {@inheritDoc}
 */
@Override
public String encrypt(String password){...}

{@link}

当您想要链接到其他符号（类、方法、字段）时使用它。请记住，使用 # 会显示类的字段方法。

适用于：类、接口、枚举、字段和方法。

示例

/**
 * This class is similar to {@link MyLittleClass} but the {@link #myNewLittleMethod(int, int)} 
 * is faster than {@link MyLittleClass#myNewLittleMethod(int, int)}
 */
public class MyNewLittleClass{...}

{@value #STATIC_FIELD}

使用它来打印 static 变量（常量）的值。

适用于：类、接口、枚举、字段和方法，但仅引用静态字段。

/**
 * This class makes a lot of calculations based on the magic number 
 * that is {@value #MY_MAGIC_NUMBER}
 */
public class MyLittleClass{...}

关注点

我每天都会注意到的一件事是，大多数时候，类和方法的名称都非常清楚它们的作用，但这并不能成为不做文档的借口！

此外，不要过多地扩展文档的内容，尤其是在实现文档方面，否则代码将变得难以阅读。

历史

  • 2013 年 9 月 24 日：创建文章
© . All rights reserved.