title: Javadoc comments vs block comments?
body: <p>When is it appropriate to use a block comment at the beginning of methods, and when is it appropriate to use a javadoc-style comment? </p>
  
  <p>From the "Comments" section of the <a href="http://www.oracle.com/technetwork/java/codeconventions-141999.html#385" rel="noreferrer">Java style guide</a>, I found this:</p>
  
  <blockquote>
    <p>Java programs can have two kinds of
    comments: implementation comments and
    documentation comments. Implementation
    comments are those found in C++, which
    are delimited by <code>/*...*/</code>, and //.
    Documentation comments (known as "doc
    comments") are Java-only, and are
    delimited by <code>/**...*/</code>. Doc comments
    can be extracted to HTML files using
    the javadoc tool.</p>
    
    <p>Implementation comments are meant for
    commenting out code or for comments
    about the particular implementation.
    Doc comments are meant to describe the
    specification of the code, from an
    implementation-free perspective. to be
    read by developers who might not
    necessarily have the source code at
    hand.</p>
  </blockquote>
  
  <p>So, another way to phrase my question would be: When do methods deserve a specification of the code, from an implementation-free perspective (Javadoc) instead of a comment about a particular implementation, and vice versa? Would an interface get javadoc comments, while the implementations get block comments?</p>
  
  <p><strong>edit:</strong> I think I am not conveying my question correctly, based on the answers thus far.</p>
  
  <p>Here's an example of what I want to know.</p>
  
  <pre><code>/**
   * Javadoc comment here about general implementation?
   */
  /*
   * Should I now have a separate block comment for my specific implementation?
   */
  public void foo()
  {
  ...
  }
  </code></pre>
  
  <p>The two different comment styles convey two different types of information. Are there cases when methods should have BOTH a leading javadoc comment, and a leading block comment?</p>
  
  <p>The inspiration for even asking is that Eclipse auto-generated this for me just now:</p>
  
  <pre><code>/*
   * (non-Javadoc)
   * @see my.package#process()
   */
  </code></pre>
  
  <p>And I figured there is some sort of styling going on here that isn't declared specifically in the comment specifications I link to above.</p>