java文档怎么写

需求文档一般分两类

需求调研报告

需求分析报告

调研报告：是记录的用户的原始需求，基本上可以算做是和用户沟通的原始记录。

分析报告：是对调研报告进行归类分析的结果。一个比较全面的文档了，在这个文档里面一般包含以下内容：

项目的背景

项目的目标

项目的范围

用户特点

相关技术、规范标准等

相关约束

用户的组织结构、角色等

用户需要的功能点，这些功能的优先级，业务流程、功能特点，有没有特殊需求等等

总而言之，需求分析报告的下一站是给设计人员的，设计人员看到需求分析报告就知道系统应该包含哪些功能点、权限设计、流程设计等，这些内容都可以直接从需要分析报告里面得出

1、单行（single-line）--短注释：//…… 单独行注释：在代码中单起一行注释， 注释前最好有一行空行，并与其后的代码具有一样的缩进层级。

如果单行无法完成，则应采用块注释。 注释格式：/* 注释内容 */ 行头注释：在代码行的开头进行注释。

主要为了使该行代码失去意义。 注释格式：// 注释内容 行尾注释：尾端（trailing）--极短的注释，在代码行的行尾进行注释。

一般与代码行后空8（至少4）个格，所有注释必须对齐。 注释格式：代码 + 8（至少4）个空格 + // 注释内容 2、块（block）--块注释：/*……*/ 注释若干行，通常用于提供文件、方法、数据结构等的意义与用途的说明，或者算法的描述。

一般位于一个文件或者一个方法的前面，起到引导的作用，也可以根据需要放在合适的位置。这种域注释不会出现在HTML报告中。

注释格式通常写成： /* * 注释内容 */ 3、文档注释：/**……*/ 注释若干行，并写入javadoc文档。每个文档注释都会被置于注释定界符 /**。

*/ 。

如何写Java文档注释（Java Doc Comments）

本文翻译自How to Write Doc Comments for the Javadoc Tool，但是精简了一些私以为不重要的东西

本文不讨论如何使用javadoc工具自动生成文档的方法，而是主要探讨应该如何去写文档注释

业余时间整理，难免有遗漏或错误，如有发现欢迎指正

转载地址：网页链接

文档注释概览

“文档注释”（Java Doc Comments）是专门为了用javadoc工具自动生成文档而写的注释，它是一种带有特殊功能的注释。

文档注释与一般注释的最大区别在于起始符号是/**而不是/*或//。

比如：

/**这是文档注释*/

/* 这是一般注释*/

// 这是一般注释

在一些IDE（比如Eclipse）中，文档注释会以不同于普通注释的颜色高亮显示。

此外，文档注释只负责描述类（class）、接口（interface）、方法（method）、构造器（constructor）、成员字段（field）。相应地，文档注释必须写在类、接口、方法、构造器、成员字段前面，而写在其他位置，比如函数内部，是无效的文档注释。

文档注释采用HTML语法规则书写，支持HTML标记（tag），同时也有一些额外的辅助标记。需要注意的是，这些标记不是给人看的（通常他们的可读性也不好），他们的作用是为了javadoc工具更好地生成最终文档。所以，虽然有些标记写起来麻烦且看着不直观，还是要老老实实按规矩写滴。

原文地址：网页链接

每个非 private 方法的参数说明，像 getter/setter 这样简单的就省略掉。主要是关键方法和类的设计要有说明。另外，一些方法有内部的实现约定，也就是前提条件，这个在技术上没办法验证的或验证它会影响性能等，我们就只在文档中说明，不在代码中检查了。举个例子，java.util.ArrayList 不是一个线程安全的集合实现类，它就在文档中说明了这点，另一个就是 equals 和 hashcode 方法在你覆盖它时应该同时按相同的算法覆盖两个，只覆盖一个就不符合设计约定。再一个就是简要说明你的关键方法和类是如何设计的。

一个好的文档可以用来回答 What, Why & hoW 这三个 W。

如果你参与了项目，最好写清楚参与的项目的时间，项目描述，自己在这个项目中的主要责任，以及在项目中用到的技术和自己在项目中学到的东西完成了xxx部分编码/测试/设计，（在xxx时间内）实现了yyyy功能，使得项目获得了zzzz收益，获得dddd奖励。

可以在项目描述中谈谈自己在实现某项功能时用到了什么技术，如用MySQL的 limit语句实现分页功能先介绍一下项目要实现的功能，在介绍下程序的结构划分（MVC），再谈下MVC各是用什么技术实现的（如View用了JSP、JSTL,Controller使用Struts2的过滤器。

），然后介绍下实现主要功能时具体用了哪些技术（建议你多谈点对AJAX的理解）。