title: What reasons and circumstances should javadoc/phpdoc be chosen over regular comments?
body: <p>What reasons and circumstances should javadoc/phpdoc be chosen over regular comments? I know what the syntax difference is but why use one or the other. Is it mainly semantic or are there other reasons why I should use one over the other, and what are they?</p>
  
  <p>I don't really understand the purpose of javadoc/phpdoc comments. What is wrong with the next block of code? ... is the <code>/**</code> just a way of making certain comments turn a different colour in the editor ... some editors don't differentiate (vanilla sublime doesn't seem to) ?</p>
  
  <pre><code>/*
   * This block is wrapped in /** */ not /* */
   * Some documentation goes here
   * Below is copied from http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
   * @param  url  an absolute URL giving the base location of the image
   * @param  name the location of the image, relative to the url argument
   * @return      the image at the specified URL
   * @see         Image
   */ 
  </code></pre>
  
  <p>Another question ... would there be any reason why I should use both <code>/** */</code> and <code>/* */</code> in the same file?</p>
  
  <p>Final question ... Why are javadoc/phpdoc comments seemingly associated with classes ... but yet I have seen them used as sort of introduction comments to a page which is what I originally understood them to be?</p>
  
  <p>actually yet another ... at the risk of answering my own question I wonder are the javadoc/phpdoc comments really just a way of differentiating between comments that were written automatically by the tool and ones that were written by the developer?</p>