javadoc- java api 文档生成器.htm

javn的Java书籍JAVA集合框架.rar我看过了是很有帮助的

</PRE></BLOCKQUOTE><!-- ================= DOCUMENTATION COMMENTS ==================== -->
<P><A name=documentationcomments></A></P>
<H3>文档注释 </H3>
<BLOCKQUOTE>
  <P><A name=comments></A></P>
  <H3>注释源代码</H3>
  <P>可以在源代码中任何实体（类、接口、方法、构造函数或域）声明的前面包括文档注释。它们也称为 Javadoc 注释，并且文件必须用 HTML 
  编写，它们应使用 HTML 实体并可使用 HTML 标记。用户可使用自己浏览器支持的任何 HTML 版本；我们编写的标准 doclet 
  可在其它地方（文档注释外部）生成 HTML 3.2-兼容代码，其中包括级联样式表单和框架。（由于框架集，我们在每个生成文件前面添加了“HTML 4.0”。） 
  </P>
  <P>例如，小于（<CODE>&lt;</CODE>）和大于（<CODE>&gt;</CODE>）符号的实体应该写为 
  <CODE>&amp;lt;</CODE> 和 <CODE>&amp;gt;</CODE>。类似地，与符号（<CODE>&amp;</CODE>）应该写为 
  <CODE>&amp;amp;</CODE>。在下面的示例中显示了粗体 HTML 标记 &lt;b&gt;。</P>
  <P>下面是文档注释： </P><PRE>/**
 * 这是 &lt;b&gt;doc&lt;/b&gt; 注释。
 * @see java.lang.Object
 */
</PRE>
  <P>文档注释由开始注释的字符 <CODE>/**</CODE> 和结束注释的字符 <CODE>*/</CODE> 之间的字符组成。文本分成一行或多行。当 
  javadoc 
  解析文档注释时，将去掉每行中的前导星号（<CODE>*</CODE>）；初始星号（<CODE>*</CODE>）字符前面的空格和制表字符也丢弃。如果省略一行上的前导星号，则所有前导空格将被去除。（在某种程度上，可以忽略前导星号。由于省略前导星号导致问题的一种情况是用 
  <CODE>&lt;pre&gt;</CODE> 标记格式化多行的缩进时，例如样本代码所示。没有前导星号，生成文档中的缩进将丢失，因为前导空格被删除。） 
  </P>
  <P>每个文档注释的首句应该为概览名，包含所声明实体的完整简要描述。该语句在第一个句号处结束后跟空格、制表或行结束符，或在第一个 <A 
  href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#javadoctags">标记</A> 
  处结束。Javadoc 将首句复制到 HTML 页顶部的成员概览中。</P>
  <P>文档注释只有在位于类、接口、构造函数、方法或域声明前面才能被识别。每个声明只有一个文档注释为 Javadoc 工具所识别。</P>
  <P>当在文档注释中嵌入 HTML 标记时，不应使用 HTML 标题标记例如 &lt;H1&gt; 和 &lt;H2&gt;，因为 Javadoc 
  创建完全结构化的文档，而这些标记将会干扰所生成文档的格式。</P>
  <P>以字符 <CODE>@</CODE> 开始的第一行文档注释将结束描述并开始标记段落部分。上例中的 <CODE>@see</CODE> 
  标记就是这种标记段落。</P>
  <P>有关文档注释的规范，参见 James Gosling、Bill Joy 和 Guy Steele 所著书籍 <A 
  href="http://java.sun.com/docs/books/jls/html/index.html"><EM>Java 
  语言规范</EM></A> 中的第 18 章“文档注释”。</P></BLOCKQUOTE>
<P><BR><!-- ====================== TAGS ========================= --><A 
name=javadoctags></A></P>
<H2>JAVADOC 标记</H2>
<BLOCKQUOTE>
  <P>Javadoc 解析 Java 文档注释中嵌入的特殊标记。这些文档标记可帮助自动从源代码生成完整的格式化 
  API。标记用“at”符号（<CODE>@</CODE>）开头，并区分大小写 -- 
  必须按照正确大小写字母输入它们。标记必须从一行的开头开始（位于任何前导空格和可选星号之后），否则它将被视为普通文本。按约定应将相同名字的标记放在一起，如将所有 
  <CODE>@see</CODE> 标记放在一起。</P>
  <P>有关我们将在未来版本中引入的标记的信息，参见 <A 
  href="http://java.sun.com/products/jdk/javadoc/proposed-tags.html">提议标记</A>。</P>
  <P>当前标记有： </P>
  <BLOCKQUOTE>
    <TABLE width="40%" border=0>
      <TBODY>
      <TR>
        <TD><B>标记</B></TD>
        <TD align=middle><B>引入该标记的 JDK 版本</B></TD></TR>
      <TR>
        <TD><A 
          href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#@author"><CODE>@author</CODE></A> 
        </TD>
        <TD align=middle>1.0</TD></TR>
      <TR>
        <TD><A 
          href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#@deprecated"><CODE>@deprecated</CODE></A> 
        </TD>
        <TD align=middle>1.0</TD></TR>
      <TR>
        <TD><A 
          href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#@throws"><CODE>@exception</CODE></A> 
        </TD>
        <TD align=middle>1.0</TD></TR>
      <TR>
        <TD><A 
          href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#{@link}"><CODE>{@link}</CODE></A> 
        </TD>
        <TD align=middle>1.2</TD></TR>
      <TR>
        <TD><A 
          href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#@param"><CODE>@param</CODE></A> 
        </TD>
        <TD align=middle>1.0</TD></TR>
      <TR>
        <TD><A 
          href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#@return"><CODE>@return</CODE></A> 
        </TD>
        <TD align=middle>1.0</TD></TR>
      <TR>
        <TD><A 
          href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#@see"><CODE>@see</CODE></A></TD>
        <TD align=middle>1.0</TD></TR>
      <TR>
        <TD><A 
          href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#@serial"><CODE>@serial</CODE></A> 
        </TD>
        <TD align=middle>1.2</TD></TR>
      <TR>
        <TD><A 
          href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#@serialData"><CODE>@serialData</CODE></A> 
        </TD>
        <TD align=middle>1.2</TD></TR>
      <TR>
        <TD><A 
          href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#@serialField"><CODE>@serialField</CODE></A> 
        </TD>
        <TD align=middle>1.2</TD></TR>
      <TR>
        <TD><A 
          href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#@since"><CODE>@since</CODE></A> 
        </TD>
        <TD align=middle>1.1</TD></TR>
      <TR>
        <TD><A 
          href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#@throws"><CODE>@throws</CODE></A> 
        </TD>
        <TD align=middle>1.2</TD></TR>
      <TR>
        <TD><A 
          href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#@version"><CODE>@version</CODE></A> 
        </TD>
        <TD align=middle>1.0</TD></TR></TBODY></TABLE></BLOCKQUOTE>
  <DL>
    <P><A name=@author></A></P>
    <DT><B><CODE>@author</CODE></B> <VAR>name-text</VAR> 
    <DD>当使用 -author 选项时，用指定的 <VAR>name-text</VAR> 在生成文档中添加“Author”项。文档注释可包含多个 
    <CODE>@author</CODE> 标记。可以对每个 <CODE>@author</CODE> 指定一个或多个名字。在前一种情况中，Javadoc 
    将在名字之间插入逗号（<CODE>,</CODE>）和空格。在后一种情况下，将全部文本复制到生成文档中而不进行解析。如果想要用逗号以外的本地化名字分隔符，则应每行使用多个名字。
    <P><A name=@deprecated></A></P>
    <DT><B><CODE>@deprecated</CODE></B> <VAR>deprecated-text</VAR> 
    <DD>添加注释，指示不应再使用该 API（尽管它仍可用）。Javadoc 将 <VAR>deprecated-text</VAR> 
    移动到描述前面，用斜体显示，并在它前面添加粗体警告： “不鼓励使用”。
    <P><VAR>deprecated-text</VAR> 的首句至少应该告诉用户什么时候开始不鼓励使用该 API 及使用什么替代它。Javadoc 
    仅将首句复制到概览部分和索引中。后面的语句还可解释为什么不鼓励使用它。还应包括一个指向替代 API 的 <CODE>{@link}</CODE> 
    标记（对于 Javadoc 1.2 或更新版本）： 
    <UL type=disc>
      <LI>对于 Javadoc 1.2，使用 <CODE>{@link}</CODE> 标记。这将在需要的地方创建内嵌链接。例如：<PRE>/**
 * @deprecated  在 JDK 1.1 中，被 {@link #setBounds(int,int,int,int)} 取代。
 */
</PRE>
      <LI>对于 Javadoc 1.1，标准格式是为每个 <CODE>@deprecated</CODE> 标记创建 
      <CODE>@see</CODE> 标记（它不能内嵌）。 </LI></UL>
    <P>有关不鼓励使用的信息，参见 <A 
    href="http://java.sun.com/products/jdk/1.1/docs/guide/misc/deprecation/index.html">@deprecated 
    标记</A>。</P>
    <P><A name=@exception></A></P>
    <DT><B><CODE>@exception</CODE></B> <VAR>class-name</VAR> 
    <VAR>description</VAR> 
    <DD><CODE>@exception</CODE> 标记是 <A 
    href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#@throws"><CODE>@throws</CODE></A> 
    的同义标记。
    <P><A name={@link}></A></P>
    <DT><B><CODE>{@link</CODE></B> <VAR>name</VAR> 
    <VAR>label</VAR><B><CODE>}</CODE></B> 
    <DD>插入指向指定 <A 
    href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#name"><I>name</I></A> 
    的内嵌链接。该标记中 <VAR>name</VAR> 和 <VAR>label</VAR> 的语法与 <CODE>@see</CODE> 
    标记完全相同，如下所述，但是它产生内嵌链接而不是在“参见”部分中放置链接。该标记用花括号开始并用花括号结束，以使它区别于其他内嵌文本。如果在标签内需要使用“}”，则请使用 
    HTML 实体表示法 &amp;#125; 
    <P>对于一个语句中所允许的 {@link} 标记数目没有限制。可以在文档注释的描述部分或任何标记（例如 @deprecated、@return 或 
    @param）的文本部分中使用该标记。</P>
    <P>例如，下面是一个引用 <CODE>getComponentAt(int, int)</CODE> 方法的注释： </P><PRE>使用 {@link #getComponentAt(int, int) getComponentAt} 方法。
</PRE>
    <P>根据它，标准 doclet 将生成如下 HTML（假定它引用相同包中另一个类）： </P><PRE>使用 &lt;a href="Component.html#getComponentAt(int, int)"&gt;getComponentAt&lt;/a&gt; 方法。
</PRE>
    <P>它在 web 页上显示为： </P><PRE>使用 <U>getComponentAt</U> 方法。
</PRE>
    <P><A name=@param></A></P>
    <DT><B><CODE>@param</CODE></B> <VAR>parameter-name</VAR><CODE> 
    </CODE><VAR>description</VAR> 
    <DD>给“参数”部分添加参数。描述可继续到下一行。
    <P><A name=@return></A></P>
    <DT><B><CODE>@return</CODE></B> <VAR>description</VAR> 
    <DD>用 <VAR>description</VAR> 文本添加“返回”部分。该文本应描述值的返回类型和容许范围。
    <P><A name=@see></A></P>
    <DT><B><CODE>@see</CODE></B> <VAR>reference</VAR> 
    <DD>添加“参见”标题，其中有指向 <VAR>reference</VAR> 的链接或文本项。文档注释可包含任意数目的 
    <CODE>@see</CODE> 标记，它们都分组在相同标题下。<CODE>@see</CODE> 标记具有三种变体；下面的第三种形式是最常用的形式。
    <DL>
      <DT><B><CODE>@see</CODE></B> <CODE>"</CODE><VAR>string</VAR>"&nbsp;&nbsp; 
      <B>注意 - 该形式在 JDK 1.2 没有用。它不打印引用文本</B>。 
      <DD>为 <VAR>string</VAR> 添加文本项。不产生链接。<VAR>string</VAR> 是不能通过 URL 
      访问的书籍或其他信息引用。Javadoc 通过查找第一个字符为双引号（<CODE>"</CODE>）的情形将它与前面的情况区分开来。例如：<PRE>     @see "Java 编程语言"
</PRE>
      <P>这将生成如下文本： </P>
      <BLOCKQUOTE>
        <DL>
          <DT><B>参见：</B> 
          <DD>"Java 编程语言" </DD></DL></BLOCKQUOTE>
      <DT><B><CODE>@see</CODE></B> <CODE>&lt;a 
      href="</CODE><VAR>URL#value</VAR><CODE>"&gt;</CODE><VAR>label</VAR><CODE>&lt;/a&gt;</CODE> 

      <DD>添加 <VAR>URL#value</VAR> 定义的链接。其中 <VAR>URL#value</VAR> 是相对 URL 或绝对 
      URL。Javadoc 通过查找第一个字符为小于符号（<CODE>&lt;</CODE>）的情形来区分它与其他情况。例如：<PRE>     @see &lt;a href="spec.html#section"&gt;Java 规范&lt;/a&gt;
</PRE>
      <P>这将生成如下链接： </P>
      <BLOCKQUOTE>
        <DL>