Lawrence D'Oliveiro wrote:
Abu Yahya wrote:
He is referring to the use of Javadoc comments. Instead of
public byte[] ReceiveChunk()
/* receives a complete chunk from the connection. */
You should write
/* receives a complete chunk from the connection. */
public byte[] ReceiveChunk()
This will allow the IDE to display the comment when you hover your mouse
above references to this method.
Why can???t this ???IDE??? handle the more natural style?
There is nothing more natural about having method/function comments after the
signature than before it. Assuming this is what you meant. And it just so
happens that in most languages I've run across there is a strong tendency to
have method/function comments precede the code that they describe.
Again, assuming that this is what you meant, you might as well get used to
source documentation tools (including their use by IDEs) requiring a specific
location for rich comments. It's not just Java and Javadoc; C# does it with
/// XML doc comments; Haddock for Haskell (and recommended style for Haskell
code comments in non-Haddock-annotated Haskell) does it as well.
Assuming "natural" locations completely falls flat on its face for a bunch of
other things, like Java annotations or C# attributes. Usually it's convenient
or necessary to decide on a standard location for such things, so as to make
the work of the processor easier or possible. But making such a choice doesn't
make a location more "natural".
I wonder where you concluded that function/method comments are more "natural"
after a function/method signature than before it? That's not the case in C or
C++ or Pascal either. About the only language that comes to my mind that
follows your convention is Eiffel.
Javadoc comments have to precede the item they document. (Abu's post did not
illustrate Javadoc comments but should have. "Lawrence D'Oliveiro" would have