[java] 注释以及javadoc使用简介-汇率换算器的实现-插曲3

 

[java] 注释以及javadoc使用简介-汇率换算器的实现-插曲3

2 本文动机介绍

虽然在写代码的过程中还是会注意添加一些注释, 但是仍然没有一个规范, 因此这里针对javadoc工具中要求的注释规范进行了简单的了解, 并将它应用到"汇率换算器"实现的代码中.

3 javadoc介绍

javadoc是将java源代码中中的注释, 按照相关的规范转化为html格式的api文档的文档生成器. 在注释过程中, 可以使用html相关的标签如:

1. <em>...</em>, <strong>...</strong> 用于强调

2. <code>...</code> 用于添加代码片断

3. <img ...> 包含图片

4. <p> 空一行

5. <a href="...">...</a> 添加链接

4 注释分类–按范围分

按照范围可以将注释分类为:

  • 包
  • 类以及接口
  • 方法
  • 其他字段

5 常用的标签

@author name     -> 作者

@version text    -> 版本号

@since text      -> 如: @since version 1.7.1

@deprecated text -> 说明该方法或类不建议使用, 如: @deprecated Use <code>setVisibile(true)</code> instead

@see link        -> 链接跳转到近似内容处, 通常是具体的类和方法, 如: @see com.rateexchange.Employee#raiseSalary(double)

6 针对包的注释

想要产生针对包的注释, 需要在每个包的目录下建立一个新的文件: package.html , 并且所有的注释文字都包括在<body>…</body>内.

7 针对类和接口的注释

恰好在类之前的注释都被解释为类的注释, 针对接口的情况也类似. 如jsoup.Node.java中的注释示例:

/**

 The base, abstract Node model. Elements, Documents, Comments etc are all Node instances.

 @author Jonathan Hedley, jonathan@hedley.net

*/

public abstract class Node implements Cloneable {

    ...

}

8 针对方法的注释

@parm variable description -> 参数注释

@return description        -> 返回值注释

@throws class description  -> 抛出的异常注释

举例说明, 如jsoup.Node.java中的注释示例:

/**

 * get an absolute url from a url attribute that may be relative (i.e. an <code>&lt;a href></code> or

 * <code>&lt;img src></code>).

 * <p/>

 * e.g.: <code>string absurl = linkel.absurl("href");</code>

 * <p/>

 * if the attribute value is already absolute (i.e. it starts with a protocol, like

 * <code>http://</code> or <code>https://</code> etc), and it successfully parses as a url, the attribute is

 * returned directly. otherwise, it is treated as a url relative to the element's {@link #baseuri}, and made

 * absolute using that.

 * <p/>

 * as an alternate, you can use the {@link #attr} method with the <code>abs:</code> prefix, e.g.:

 * <code>string absurl = linkel.attr("abs:href");</code>

 *

 * @param attributekey the attribute key

 * @return an absolute url if one could be made, or an empty string (not null) if the attribute was missing or

 * could not be made successfully into a url.

 * @see #attr

 * @see java.net.url#url(java.net.url, string)

 */

public string absurl(string attributekey) {

    ...

}

9 其他字段的注释

如对静态变量的注释, 如下:

/**

   The "Hearts" card suit

*/

public static final int HEARTS = 1;

10 在"汇率转换器"源代码中添加注释

11 执行javadoc, 并且使得中文正常显示

javadoc -d doc -sourcepath src/ -charset utf-8 -encoding utf-8 -docencoding utf-8 com.cnblogs.grassandmoon

Date: 2014-05-16 Fri

Author: Zhong Xiewei

Org version 7.8.11 with Emacs version 24

Validate XHTML 1.0

[java] 注释以及javadoc使用简介-汇率换算器的实现-插曲3的更多相关文章

  1. [java] jsoup使用简介-汇率换算器实现-插曲2

    [java] jsoup使用简介-汇率换算器实现-插曲2 // */ // ]]>   [java] jsoup使用简介-汇率换算器实现-插曲2 Table of Contents 1 系列文章 ...

  2. [java] 更好的书写equals方法-汇率换算器的实现(4)

    [java] 更好的书写equals方法-汇率换算器的实现(4) // */ // ]]>   [java] 更好的书写equals方法-汇率换算器的实现(4) Table of Content ...

  3. [java] 汇率换算器实现-插曲1-正则表达式(1)

    [java] 汇率换算器实现-插曲1-正则表达式(1) // */ // ]]> // */ // ]]>   [java] 汇率换算器实现-插曲1-正则表达式(1) Table of C ...

  4. [java] 汇率换算器实现(3)

    [java] 汇率换算器实现(3) // */ // ]]>   [java] 汇率换算器实现(3) Table of Contents 1 系列文章地址 2 前言 3 提取简单表单信息 3.1 ...

  5. [java] 汇率换算器实现(2)

    [java] 汇率换算器实现(2) // */ // ]]> // */ // ]]>   [java] 汇率换算器实现(2) Table of Contents 1 系列文章地址 2 前 ...

  6. [java] 汇率换算器实现(1)

    [java] 汇率换算器实现(1) // */ // ]]>   [java] 汇率换算器实现(1) Table of Contents 1 问题描述 2 类设计 3 初步实现 3.1 建立项目 ...

  7. 【菜鸟学Python】案例一：汇率换算

    汇率换算V1.0 案例描述: 设计一个汇率换算器程序,其功能是将外币换算成人民币,或者相反 案例分析: 分析问题:分析问题的计算部分: 确定问题:将问题划分为输入.处理及输出部分: 设计算法:计算部分 ...

  8. 汇率换算自然语言理解功能JAVA DEMO

    >>>>>>>>>>>>>>>>>>>>>>>> 欢迎转 ...

  9. Java的注释和Javadoc在eclipse生成的方法 – Break易站

    本文内容来自:Java的注释和Javadoc在eclipse生成的方法 – Break易站 1.  Java的注释 Java里有两种注释风格.下面这个写法是非常常见的 1 2 3 4 /*This i ...

随机推荐

  1. LDA和PLSA

    看了<LDA数学八卦>和July的博客,里面涉及到好多公式推导...感觉好复杂,于是记录一些重点简洁的东西,忽略大批量铺垫,直接回答LDA和PLSA是区别: 在pLSA模型中,我们按照如下 ...

  2. [ASE]sprint3 总结 & sprint4计划

    斯普润特4! 啊终于到最后一个阶段了…… 有种苦日子就要熬到头跟小组合作意犹未尽的感觉 那么开始sprint3-sprint4的衔接吐槽总结 在之前的两周也就是sprint3期间正赶上出国申请的dl, ...

  3. 【转载】解决Windows 10 局域网内共享的问题

    问题: 小米盒子,iPhone (OS 10.2) 无法访问 Win 1o共享 解决方案: 原文链接 http://www.dedoimedo.com/computers/windows-10-net ...

  4. 即时通信系统中如何实现：聊天消息加密，让通信更安全？ 【低调赠送：QQ高仿版GG 4.5 最新源码】

    加密重要的通信消息,是一个常见的需求.在一些政府部门的即时通信软件中(如税务系统),对聊天消息进行加密是非常重要的一个功能,因为谈话中可能会涉及到机密的数据.我在最新的GG 4.5中,增加了对聊天消息 ...

  5. WPF 窗口自适应

    窗口自适应就是说,当主窗口缩放的时候,内部的控件位置自动的调整,而不是隐藏掉.这主要依赖于Grid布局. 1.比如这个groupbox 本身是在一个Grid的Row中的.缩放之后,左边的button不 ...

  6. [.net 面向对象程序设计进阶] (8) 托管与非托管

    本节导读:虽然在.NET编程过程中,绝大多数内存垃圾回收由CLR(公共语言运行时)自动回收,但也有很多需要我们编码回收.掌握托管与非托管的基本知识,可以有效避免某些情况下导致的程序异常. 1.什么是托 ...

  7. Windbg用法详解

    工作空间 WinDBG的工作空间中保存了以下几种信息 调试会话状态: 包括断点,打开的源文件,用户定义的别名(alias)等. 调试器设置:包括符号文件路径,可执行映像文件路径,源文件路径,用I+/I ...

  8. css实现左栏固定右栏自适应，高度自适应的布局

    收集css中的基础知识,所以这并不是什么新鲜的技术,只是作为备忘~本文的内容如题所示,是一个简单的布局,用于左右两栏布局的页面,左侧是固定宽度,右侧占据剩余的宽度.在垂直方向,始终以高度最大的一栏为基 ...

  9. Comet实现的网页聊天程序

    “上一篇”介绍了我在c/s程序中用了那些技术,如今只谈c/s不谈b/s那未免out了,势必要写一写b/s的程序与大家共勉. 回忆做技术这些年,06年每天盯着“天轰穿”的视频不亦乐乎,估计那是一代程序员 ...

  10. Linux vim命令

    介绍 vim命令和vi的操作基本一致,vim命令的参数很多,我在这里列出了一些平时需要用的一些参数,vim主要有两个界面一个是esc的操作界面还有一个是输入i的编辑界面. 移动光标 0 (零):将光标 ...