>>分享Java编程技术,对《Java面向对象编程》等书籍提供技术支持 书籍支持  卫琴直播  品书摘要  在线测试  资源下载  联系我们
发表一个新主题 开启一个新投票 回复文章 您是本文章第 30550 个阅读者 刷新本主题
 * 贴子主题:  Java入门: 文档注释 回复文章 点赞(0)  收藏  
作者:flybird    发表时间:2020-01-08 06:42:30     消息  查看  搜索  好友  邮件  复制  引用

Java 文档注释

            Java 支持三种注释方式。前两种分别是 // /* */,第三种被称作说明注释,它以 /** 开始,以 */结束。

        说明注释允许你在程序中嵌入关于程序的信息。你可以使用 javadoc 工具软件来生成信息,并输出到HTML文件中。

        说明注释,使你更加方便的记录你的程序信息。    

javadoc 标签

            javadoc 工具软件识别以下标签:

            
标签

描述


示例
@author 标识一个类的作者 @author description
@deprecated 指名一个过期的类或成员 @deprecated description
{@docRoot} 指明当前文档根目录的路径 Directory Path
@exception 标志一个类抛出的异常 @exception exception-name explanation
{@inheritDoc} 从直接父类继承的注释 Inherits a comment from the immediate surperclass.
{@link} 插入一个到另一个主题的链接 {@link name text}
{@linkplain} 插入一个到另一个主题的链接,但是该链接显示纯文本字体 Inserts an in-line link to another topic.
@param 说明一个方法的参数 @param parameter-name explanation
@return 说明返回值类型 @return explanation
@see 指定一个到另一个主题的链接 @see anchor
@serial 说明一个序列化属性 @serial description
@serialData 说明通过writeObject( ) 和 writeExternal( )方法写的数据 @serialData description
@serialField 说明一个ObjectStreamField组件 @serialField name type description
@since 标记当引入一个特定的变化时 @since release
@throws 和 @exception标签一样. The @throws tag has the same meaning as the @exception tag.
{@value} 显示常量的值,该常量必须是static属性。 Displays the value of a constant, which must be a static field.
@version 指定类的版本 @version info

文档注释

            在开始的 /** 之后,第一行或几行是关于类、变量和方法的主要描述。

        之后,你可以包含一个或多个各种各样的 @ 标签。每一个 @ 标签必须在一个新行的开始或者在一行的开始紧跟星号(*).

        多个相同类型的标签应该放成一组。例如,如果你有三个 @see 标签,可以将它们一个接一个的放在一起。

        下面是一个类的说明注释的实例:

/* ** 这个类绘制一个条形图
*  @author  javathinker
*  @version  1.2
*/

javadoc 输出什么

        javadoc 工具将你 Java 程序的源代码作为输入,输出一些包含你程序注释的HTML文件。

        每一个类的信息将在独自的HTML文件里。javadoc 也可以输出继承的树形结构和索引。

        由于 javadoc 的实现不同,工作也可能不同,你需要检查你的 Java 开发系统的版本等细节,选择合适的 Javadoc 版本。    

实例

            下面是一个使用说明注释的简单实例。注意每一个注释都在它描述的项目的前面。

        在经过 javadoc 处理之后,SquareNum 类的注释将在 SquareNum.html 中找到。            

SquareNum.java 文件代码:

import   java . io .*;

/* *
* 这个类演示了文档注释
*  @author  Ayan Amhed
*  @version  1.2
*/

public   class   SquareNum   {
    /* *
   * This method returns the square of num.
   * This is a multiline description. You can use
   * as many lines as you like.
   *  @param  num The value to be squared.
   *  @return  num squared.
    */

    public   double   square ( double   num )   {
       return   num  *  num ;
    }
    /* *
   * This method inputs a number from the user.
   *  @return  The value input as a double.
   *  @exception  IOException On input error.
   *  @see  IOException
    */

    public   double   getNumber ( )   throws   IOException   {
       InputStreamReader   isr  =  new   InputStreamReader ( System . in ) ;
       BufferedReader   inData  =  new   BufferedReader ( isr ) ;
       String   str ;
       str  =  inData . readLine ( ) ;
       return   ( new   Double ( str ) ) . doubleValue ( ) ;
    }
    /* *
   * This method demonstrates square().
   *  @param  args Unused.
   *  @return  Nothing.
   *  @exception  IOException On input error.
   *  @see  IOException
    */

    public   static   void   main ( String   args [ ] )   throws   IOException
    {
       SquareNum   ob  =  new   SquareNum ( ) ;
       double   val ;
       System . out . println ( " Enter value to be squared:  " ) ;
       val  =  ob . getNumber ( ) ;
       val  =  ob . square ( val ) ;
       System . out . println ( " Squared value is  "  +  val ) ;
    }
}

如下,使用 javadoc 工具处理 SquareNum.java 文件:

$ javadoc SquareNum.java

Loading source file SquareNum.java...

Constructing Javadoc information...

Standard Doclet version 1.5.0_13

Building tree for all the packages and classes...

Generating SquareNum.html...

SquareNum.java:39: 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...

Generating stylesheet.css...

1 warning

$

      


程序猿的技术大观园:www.javathinker.net



[这个贴子最后由 flybird 在 2020-01-31 22:07:50 重新编辑]
  Java面向对象编程-->流程控制
  JavaWeb开发-->Java语言的基本语法和规范
  JSP与Hibernate开发-->使用Session(Ⅰ)
  Java网络编程-->使用过滤器
  精通Spring-->使用JPA和注解
  Vue3开发-->Spring、JPA与Hibernate的整合
  JDK17的新特性
  Java函数式接口和Stream流
  孙卫琴的视频课程的源代码下载
  Java内存设置详解(含内存溢出问题的解决)
  Java注解的定义和使用
  NoClassDefFoundError和ClassNotFoundException的区别
  java常见的几种调用机制:同步调用,异步调用,回调
  Eclipse使用指南:创建Java项目的步骤
  Java设计模式:享元模式
  Socket服务器的整体架构
  Java入门实用代码:死锁及解决方法
  Java入门实用代码: 字符串格式化
  中国有多少程序员?现在还值得学java吗?
  java Pattern和Matcher详解
  初学者该学哪种编程语言
  更多...
 IPIP: 已设置保密
楼主      
1页 0条记录 当前第1
发表一个新主题 开启一个新投票 回复文章


中文版权所有: JavaThinker技术网站 Copyright 2016-2026 沪ICP备16029593号-2
荟萃Java程序员智慧的结晶,分享交流Java前沿技术。  联系我们
如有技术文章涉及侵权,请与本站管理员联系。