Javadoc

最新推荐文章于 2025-05-17 19:29:34 发布

mikimoto_

最新推荐文章于 2025-05-17 19:29:34 发布

阅读量808

点赞数 1

CC 4.0 BY-SA版权

本文链接：https://blog.csdn.net/mikimoto_/article/details/102916528

**什么是javadoc*

javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。
javadoc命令是用来生成自己API文档的，使用方式：使用命令行在目标文件所在目录输入javadoc +文件名.java。
javadoc图册
在这里插入图片描述

如何在源代码中用Javadoc标签写注释及如何创建Javadoc文档。
Javadoc注释由Javadoc标签和描述性文本组成，可以为类、接口添加注释，也可为构造函数、值域、方法等类中的元素添加注释。可以通过代码模板快速的录入Javadoc注释，也可以选择通过Javadoc对话框以一种形象化的方式录入Javadoc注释。虽然在Java文件中编写注释后，可以马上切换到内容窗格的Doc视图页代码中对应的Javadoc文档，但在Doc视图页中生成的文档是不完整的"范本"。第一，没有导航树。第二，没有生成通过@see或@link关联内容的链接。

常用标记

标签	说明
@author 作者	作者标识
@version 版本号	版本号
@param 参数名描述	方法的入参名及描述信息，如入参有特别要求，可在此注释
@return 描述	对函数返回值的描述/注释
@deprecated 过期文本	标识随着程序版本的提升，当前API已经过期，仅为了保证兼容性依然存在，以此告知开发者不应再用这个API
@throws 异常类名	构造函数或方法会抛出的异常
@exception 异常类名	同@throws
@see 引用	引用，查看相关的内容，如类，方法，变量等，必须顶头写
@since 描述文本	API在什么程序的什么版本后开发支持
{@link 包.类#成员标签}	链接到某个特定的成员对应的文档中。同@see，但可写在任意位置
{@value}	当对常量注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值
{@code}	{@code text}将文本标记为code，会被解析成 text } ,在Javadoc成只要涉及到类名或者方法名，都需要使用@code进行标记
@inheritDoc	用于继承父类中的Javadoc，父类的文档注释，被继承到了子类

Javadoc的注释规范

一、 Java文档

// 注释一行
/ *    */ 注释若干行  
/**   ……*/  注释若干行，写入Javadoc文档

二、文档格式
写在类上的文档标注一般分为三段：

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

生成文档是HTML格式。
换行<br>
分段<p>(写在段前）)

例：

/** 
* show 方法的简述.
* <p>show 方法的详细说明第一行<br> 
* show 方法的详细说明第二行 
* @param b true 表示显示，false 表示隐藏 
* @return 没有返回值 
*/ 
public void show(boolean b) {
    frame.show(b);
    }

Javadoc的基本语法使用

1 @author：作者标识
例：

// 纯文本作者
@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>

@version ：版本号
例：

package com.sun.org.apache.xml.internal.resolver;
 /**
 * @version 1.0
 */
public class Resolver extends Catalog {}

@param：方法的入参名及描述信息，如入参有特别要求，可在此注释**
例：

/**
* @param <E> the type of elements in this list
*/
public interface List<E> extends Collection<E> {}

@return：对函数返回值的描述/注释
例：

/**
* @return {@code true} if the {@code String} is not {@code null}, its
*/
public static boolean hasText(@Nullable String str){}

5.@throws：构造函数或方法会抛出的异常

/**
* @throws IllegalArgumentException when the given source contains invalid encoded sequences
*/
public static String uriDecode(String source, Charset charset){}

@exception：同@throws
例：
/**

@exception IllegalArgumentException if key is null.
*/
public static Object get(String key) throws IllegalArgumentException {}

@see：引用，查看相关的内容，如类，方法，变量等，必须顶头写
例一：

/**
 * @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>> {}

例二：

/**
* @see java.net.URLDecoder#decode(String, String)
*/
public static String uriDecode(String source, Charset charset){}

@since：API在什么程序的什么版本后开发支持
例：

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 {}

@link：{@link 包名.类名#方法名(参数类型)}
例：

// 完全限定的类名
{@link java.lang.Character}

// 省略包名
{@link String}

// 省略类名，表示指向当前的某个方法
{@link #length()}

// 包名.类名.方法名(参数类型)
{@link java.lang.String#charAt(int)}

10.@value：当对常量注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值
例：

/** 默认数量 {@value} */
private static final Integer QUANTITY = 1;

@code：{@code text}将文本标记为code，会被解析成 text } ,在Javadoc成只要涉及到类名或者方法名，都需要使用@code进行标记
@inheritDoc：用于继承父类中的Javadoc，父类的文档注释，被继承到了子类
@inheritDoc用于注解在重写方法或者子类上，用于继承父类中的Javadoc
基类的文档注释被继承到了子类
子类可以再加入自己的注释（特殊化扩展）
@return @param @throws 也会被继承