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?
I don't really understand the purpose of javadoc/phpdoc comments. What is wrong with the next block of code? ... is the /** 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) ?
/*
* 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
*/
Another question ... would there be any reason why I should use both /** */ and /* */ in the same file?
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?
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?
The whole reason people use Javadoc is for consistency and readability - if you know the syntax it makes it easy to look at someone else's code (or vice-versa), and understand the meaning straight away. Rather than having something like:
// This method is used for counting sheep just before bed time
// It's really awesome, and takes the bed-time, and also age,
// And also number of sheep, in reverse order.
Which takes time to process; it's far nicer to see:
/**
* Count the number of sheep at bedtime
*
* @author Tom Walters
*
* @param sheep The number of sheep to count
* @param age The age of the person going to bed
* @param bedTime The time of going to bed in 24hr format
* @return The sheep were counted successfully
*/
Immediately you can see how many parameters there are, and what each of them is for. The same goes for the return type. It's also highly useful when working in teams to have the author up there, then you know who to shout at when the sheep go astray.
As for the /** - it helps differentiate this style from things like random comments and on-line comments and is a nice convention to help Javadoc stick out when browsing code.
As a rule you you'll be maintaining code more than you write it, so having a well-defined syntax like this is a great idea - it'll lead to you being to allocate more time to thinking about problem-solving, rather than deciphering large blocks of text for basic information.