epubjs
Version:
Render ePub documents in the browser, across many devices
83 lines (81 loc) • 10.1 kB
HTML
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Comments</title><link rel="stylesheet" href="core.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"/></head><body><div class="sect1" title="Comments"><div class="titlepage"><div><div><h1 class="title"><a id="learnjava3-CHP-4-SECT-2"/>Comments</h1></div></div></div><p><a id="I_indexterm4_id647196" class="indexterm"/> <a id="idx10142" class="indexterm"/> <a id="idx10186" class="indexterm"/> Java supports both C-style <span class="emphasis"><em>block
comments</em></span> delimited by <a id="I_indexterm4_id647229" class="indexterm"/><a id="I_indexterm4_id647235" class="indexterm"/><code class="literal">/*</code> and <a id="I_indexterm4_id647245" class="indexterm"/><a id="I_indexterm4_id647250" class="indexterm"/><a id="I_indexterm4_id647256" class="indexterm"/><code class="literal">*/</code> and C++-style
<span class="emphasis"><em>line comments</em></span> indicated by <code class="literal">//</code>:</p><a id="I_4_tt114"/><pre class="programlisting"> <code class="cm">/* This is a</code>
<code class="cm"> multiline</code>
<code class="cm"> comment. */</code>
<code class="c1">// This is a single-line comment</code>
<code class="c1">// and so // is this</code></pre><p>Block comments have both a beginning and end sequence and can cover
large ranges of text. However, they cannot be “nested,” meaning that you
can’t have a block comment inside of a block comment without the compiler
getting confused. Single-line comments have only a start sequence and are
delimited by the end of a line; extra <code class="literal">//</code> indicators inside a single line have no
effect. Line comments are useful for short comments within methods; they
don’t conflict with block comments, so you can still comment out larger
chunks of code in which they are nested.</p><div class="sect2" title="Javadoc Comments"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-4-SECT-2.1"/>Javadoc Comments</h2></div></div></div><p><a id="idx10164" class="indexterm"/>A block comment beginning with <a id="I_indexterm4_id647319" class="indexterm"/><a id="I_indexterm4_id647325" class="indexterm"/><code class="literal">/**</code> indicates a special
<a id="I_indexterm4_id647336" class="indexterm"/><span class="emphasis"><em>doc</em></span><span class="emphasis"><em>comment</em></span>. A
doc comment is designed to be extracted by automated documentation
generators, such as the JDK’s <span class="emphasis"><em>javadoc</em></span> program. A
doc comment is terminated by the next <code class="literal">*/</code>, just as with a regular block comment.
Within the doc comment, lines beginning with <a id="I_indexterm4_id647358" class="indexterm"/><code class="literal">@</code> are interpreted as
special instructions for the documentation generator, giving it
information about the source code. By convention, each line of a doc
comment begins with a <code class="literal">*</code>, as shown in
the following example, but this is optional. Any leading spacing and the
<code class="literal">*</code> on each line are ignored:</p><a id="I_4_tt115"/><pre class="programlisting"> <code class="cm">/**</code>
<code class="cm"> * I think this class is possibly the most amazing thing you will</code>
<code class="cm"> * ever see. Let me tell you about my own personal vision and</code>
<code class="cm"> * motivation in creating it.</code>
<code class="cm"> * <p></code>
<code class="cm"> * It all began when I was a small child, growing up on the</code>
<code class="cm"> * streets of Idaho. Potatoes were the rage, and life was good...</code>
<code class="cm"> *</code>
<code class="cm"> * @see PotatoPeeler</code>
<code class="cm"> * @see PotatoMasher</code>
<code class="cm"> * @author John 'Spuds' Smith</code>
<code class="cm"> * @version 1.00, 19 Dec 2006</code>
<code class="cm"> */</code>
<code class="kd">class</code> <code class="nc">Potato</code> <code class="o">{</code></pre><p><span class="emphasis"><em>javadoc</em></span> creates HTML documentation for
classes by reading the source code and pulling out the embedded comments
and <code class="literal">@</code> tags. In this example, the tags
cause author and version information to be presented in the class
documentation. The <code class="literal">@see</code> tags produce
hypertext links to the related class documentation.</p><p>The compiler also looks at the doc comments; in particular, it is
interested in the <a id="I_indexterm4_id647422" class="indexterm"/><code class="literal">@deprecated</code> tag, which
means that the method has been declared obsolete and should be avoided
in new programs. The fact that a method is deprecated is noted in the
compiled class file so a warning message can be generated whenever you
use a deprecated feature in your code (even if the source isn’t
available).</p><p>Doc comments can appear above class, method, and variable
definitions, but some tags may not be applicable to all of these. For
example, the <a id="I_indexterm4_id647445" class="indexterm"/><code class="literal">@exception</code> tag can only
be applied to methods. <a class="xref" href="ch04s02.html#learnjava3-CHP-4-TABLE-1" title="Table 4-1. Doc comment tags">Table 4-1</a>
summarizes the tags used in doc comments.</p><div class="table"><a id="learnjava3-CHP-4-TABLE-1"/><p class="title">Table 4-1. Doc comment tags</p><div class="table-contents"><table summary="Doc comment tags" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; "><colgroup><col/><col/><col/></colgroup><thead><tr><th style="text-align: left"><p>Tag</p></th><th style="text-align: left"><p>Description</p></th><th style="text-align: left"><p>Applies to</p></th></tr></thead><tbody><tr><td style="text-align: left"><p> <a id="I_indexterm4_id647518" class="indexterm"/> <code class="literal">@see</code>
</p></td><td style="text-align: left"><p>Associated class name</p></td><td style="text-align: left"><p>Class, method, or
variable</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm4_id647549" class="indexterm"/> <code class="literal">@author</code>
</p></td><td style="text-align: left"><p>Author name</p></td><td style="text-align: left"><p>Class</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm4_id647580" class="indexterm"/> <code class="literal">@version</code>
</p></td><td style="text-align: left"><p>Version string</p></td><td style="text-align: left"><p>Class</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm4_id647611" class="indexterm"/> <code class="literal">@param</code>
</p></td><td style="text-align: left"><p>Parameter name and
description</p></td><td style="text-align: left"><p>Method</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm4_id647642" class="indexterm"/> <code class="literal">@return</code>
</p></td><td style="text-align: left"><p>Description of return
value</p></td><td style="text-align: left"><p>Method</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm4_id647674" class="indexterm"/> <code class="literal">@exception</code>
</p></td><td style="text-align: left"><p>Exception name and
description</p></td><td style="text-align: left"><p>Method</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm4_id647705" class="indexterm"/> <code class="literal">@deprecated</code>
</p></td><td style="text-align: left"><p>Declares an item to be
obsolete</p></td><td style="text-align: left"><p>Class, method, or
variable</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm4_id647737" class="indexterm"/> <code class="literal">@since</code>
</p></td><td style="text-align: left"><p>Notes API version when item was
added</p></td><td style="text-align: left"><p>Variable</p></td></tr></tbody></table></div></div><div class="sect3" title="Javadoc as metadata"><div class="titlepage"><div><div><h3 class="title"><a id="learnjava3-CHP-4-SECT-2.1.1"/>Javadoc as metadata</h3></div></div></div><p><a id="I_indexterm4_id647769" class="indexterm"/>Javadoc tags in doc comments represent <a id="I_indexterm4_id647778" class="indexterm"/><span class="emphasis"><em>metadata</em></span> about the source code;
that is, they add descriptive information about the structure or
contents of the code that is not, strictly speaking, part of the
application. Some additional tools extend the concept of Javadoc-style
tags to include other kinds of metadata about Java programs that are
carried with the compiled code and can more readily be used by the
application to affect its compilation or runtime behavior. The Java
<span class="emphasis"><em>annotations</em></span> facility provides a more formal and
extensible way to add metadata to Java classes, methods, and
variables. We’ll talk about annotations in <a class="xref" href="ch07.html" title="Chapter 7. Working with Objects and Classes">Chapter 7</a>. However, we should mention that there
is a <code class="literal">@deprecated</code> annotation that
has the same meaning as that of the Javadoc tag of the same name, and
you may prefer to use that.<a id="I_indexterm4_id647810" class="indexterm"/><a id="I_indexterm4_id647817" class="indexterm"/><a id="I_indexterm4_id647824" class="indexterm"/></p></div></div></div></body></html>