Javadoc告诉你怎么维护好业务代码

298次阅读
没有评论

共计 5345 个字符,预计需要花费 14 分钟才能阅读完成。

Javadoc写在类上面

第一段:概要描述,通常用一句或者一段话简要描述该类的作用,以英文句号作为结束
第二段:详细描述,通常用一段或者多段话来详细描述该类的作用,一般每段话都以英文句号作为结束
第三段:文档标注,用于标注作者、创建时间、参阅类等信息

单行示例:

/**
 * Utility class used to help generate return values for calls to {@link Object#toString()}.
 */
public class ToStringUtil {

多行示例:

/**
 * Class {@code Object} is the root of the class hierarchy.
 * Every class has {@code Object} as a superclass. All objects,
 * including arrays, implement the methods of this class.
 *
 * @author  unascribed
 * @see     java.lang.Class
 * @since   JDK1.0
 */
public class Object {
package cn.peiluming.test;

/**
 * {@link cn.peiluming.test.JavaDoc#main(String[])} 包名.类名.方法名(参数类型)
 * {@link JavaDoc#main(String[])} 省略包名
 * {@link #main(String[])} 省略类名,表示指向当前的某个方法
 * {@link cn.peiluming.test.JavaDoc} 完全限定的类名
 *
 * @author 裴路明
 * @create 2021/1/15 22:16
 */
public class JavaDoc {
    public static void main(String[] args) {

    }
}
  • Tip:一般在Javadoc中只要涉及到类名或者方法名,都需要使用@code进行标记
  • 详细描述中可以使用html标签,如<p>、<pre>、<a>、<ul>、<i>等标签, 通常详细描述都以段落p标签开始。
  • 详细描述和概要描述中间通常有一个空行来分割
package org.thymeleaf.util;

/**
 *
 * Utility methods for String objects.
 *
 * <p>
 * This class is used as a basis for the methods offered by
 * {@link org.thymeleaf.expression.Strings}, which in turn are the
 * methods offered by the {@code #strings} utility object in variable
 * expressions.
 * </p>
 *
 * @author Daniel Fern&aacute;ndez
 * @author Le Roux Bernard
 * @author Soraya S&aacute;nchez Labandeira
 * @since 1.0
 */
public final class StringUtils {
/**
* @param <E> the type of elements in this list
*/
public interface List<E> extends Collection<E> {}
// 纯文本作者
@author Rod Johnson

// 纯文本作者,邮件
@author Igor Hersht, igorh@ca.ibm.com

// 超链接邮件 纯文本作者
@author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>

// 纯文本邮件
@author shane_curcuru@us.ibm.com

// 纯文本 组织
@author Apache Software Foundation

// 超链接组织地址 纯文本组织
@author <a href="https://jakarta.apache.org/turbine"> Apache Jakarta Turbine</a>
/**
 * @see IntStream
 * @see LongStream
 * @see DoubleStream
 * @see <a href="package-summary.html">java.util.stream</a>
 * /
public interface Stream<T> extends BaseStream<T, Stream<T>> {}
package java.util.stream;

/**
* @since 1.8
*/
public interface Stream<T> extends BaseStream<T, Stream<T>> {}
package org.springframework.util;

/**
* @since 16 April 2001
*/
public abstract class StringUtils {}
package com.sun.org.apache.xml.internal.resolver;
 /**
 * @version 1.0
 */
public class Resolver extends Catalog {}

Javadoc写在方法上

第一段:概要描述,通常用一句或者一段话简要描述该方法的作用,以英文句号作为结束
第二段:详细描述,通常用一段或者多段话来详细描述该方法的作用,一般每段话都以英文句号作为结束
第三段:文档标注,用于标注参数、返回值、异常、参阅等
/**
     * 根据博客Id和标签Id插入中间表
     *
     * @param blogId 博客Id
     * @param tagId  标签Id
     * @return 影响行数
     */
    int insertBlogsTags(@Param("blogId") String blogId, @Param("tagId") String tagId);
 /**
     * 文件复制
     *
     * @param src 源目录
     * @param destDir 目标目录
     * @param fileName 文件名
     * @throws IOException IO异常
     */
    private void copyFile(String src, String destDir, String fileName) throws IOException {
/**
    *@exception SQLException if a database error occurs
    */
    protected Connection open() throws SQLException {
/**
* @see java.net.URLDecoder#decode(String, String)
*/
public static String uriDecode(String source, Charset charset){}
/** 默认数量 {@value} */
private static final Integer QUANTITY = 1;
/**
     * Returns the URI of this engine.
     * @return the URI
     */
    public abstract String engineGetURI();

/** @inheritDoc */
    public final String engineGetURI() {
        return Canonicalizer.ALGO_ID_C14N_OMIT_COMMENTS;
    }
/**
     * Is this Doc item an
     * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#class">ordinary
     * class</a>?
     * (i.e. not an interface, annotation type, enum, exception, or error)?
     *
     * @return true if it represents an ordinary class
     */
    boolean isOrdinaryClass();
/**
     * @deprecated
     */
    @Deprecated
    public void invoke(java.rmi.server.RemoteCall call) throws Exception {

生成Javadoc

  1. IDEA 的 JavaDoc 生成功能在菜单 Tools->Generate JavaDoc 项里面。

Javadoc告诉你怎么维护好业务代码

Javadoc告诉你怎么维护好业务代码

生成JavaDoc的源代码范围,不建议以整个Project
生成JavaDoc到哪个目录下面
表示的是需要生成的JavaDoc以何种语言版本展示,建议在此填写 zh_CN,这样生成的 JavaDoc 就是中文版本的
非常重要,是填写直接向 javadoc.exe 传递的参数内容

建议:-encoding UTF-8 -charset UTF-8 -windowtitle "XXwiki" -link http://docs.Oracle.com/javase/7/docs/api

  • -encoding UTF-8 表示你的源代码(含有符合JavaDoc标准的注释)是基于UTF-8编码的
  • -charset UTF-8 表示在处理并生成JavaDoc超文本时使用的字符集也是以UTF-8为编码
  • -windowtitle 表示生成的JavaDoc超文本在浏览器中打开时,浏览器窗口标题栏显示的文字内容
  • -link 涉及到很多对其他外部Java类的引用,是使用全限定名称还是带有超链接的短名称
    举例:

    我创建了一个方法 public void func(String arg),这个方法在生成 JavaDoc 时如果不指定 -link 参数,则 JavaDoc 中对该方法的表述就会自动变为 public void func(java.lang.String arg),因为 String 这个类对我自己实现的类来讲就是外部引用的类,虽然它是 Java 标准库的类。如果指定了 -link http://docs.oracle.com/javase/7/docs/api 参数,则 javadoc.exe 在生成 JavaDoc 时,会使用 String 这样的短名称而非全限定名称 java.lang.String,同时自动为 String 短名称生成一个超链接,指向官方 JavaSE 标准文档 http://docs.oracle.com/javase/7/docs/api 中对 String 类的详细文档地址。-link 实质上是告诉 javadoc.exe 根据提供的外部引用类的 JavaDoc 地址去找一个叫 package-list 的文本文件,在这个文本文件中包含了所有外部引用类的全限定名称,因此生成的新 JavaDoc 不必使用外部引用类的全限定名,只需要使用短名称,同时可以自动创建指向其外部引用 JavaDoc 中的详细文档超链接。我创建了一个方法 public void func(String arg),这个方法在生成 JavaDoc 时如果不指定 -link 参数,则 JavaDoc 中对该方法的表述就会自动变为 public void func(java.lang.String arg),因为 String 这个类对我自己实现的类来讲就是外部引用的类,虽然它是 Java 标准库的类。如果指定了 -link http://docs.oracle.com/javase/7/docs/api 参数,则 javadoc.exe 在生成 JavaDoc 时,会使用 String 这样的短名称而非全限定名称 java.lang.String,同时自动为 String 短名称生成一个超链接,指向官方 JavaSE 标准文档 http://docs.oracle.com/javase/7/docs/api 中对 String 类的详细文档地址。-link 实质上是告诉 javadoc.exe 根据提供的外部引用类的 JavaDoc 地址去找一个叫 package-list 的文本文件,在这个文本文件中包含了所有外部引用类的全限定名称,因此生成的新 JavaDoc 不必使用外部引用类的全限定名,只需要使用短名称,同时可以自动创建指向其外部引用 JavaDoc 中的详细文档超链接。

JavaDoc生成完毕,如图:

Javadoc告诉你怎么维护好业务代码

Javadoc告诉你怎么维护好业务代码

正文完
 0
裴先生
版权声明:本站原创文章,由 裴先生 2021-01-15发表,共计5345字。
转载说明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。
评论(没有评论)
本站勉强运行: