JavaDoc\uc5d0 \ub300\ud55c \uba87 \uac00\uc9c0 \ud301<\/p>\n
It’s another Java 5-ish post which might not attract people, yet is very important. I find a lot of wrong or out-of-date JavaDoc due to lack of understandings on useful JavaDoc tags. Bad JavaDoc affects the quality of in-house softwares seriously, so knowing and using the following tips will improve the quality of your projects significantly.<\/p>\n
\uc0ac\ub78c\ub4e4\ud55c\ud14c \ubcc4\ub85c \ud765\ubbf8\uac00 \uc5c6\uc744, \ud558\uc9c0\ub9cc \uc544\uc8fc \uc911\uc694\ud55c \ub610 \ud558\ub098\uc758 Java 5 \uc2a4\ub7ec\uc6b4 \uc774\uc57c\uae30\uc785\ub2c8\ub2e4. JavaDoc \ud0dc\uadf8\uc5d0 \ub300\ud55c \uc774\ud574 \ubd80\uc871\uc73c\ub85c \uc798\ubabb\ub418\uac70\ub098 \ucca0\uc9c0\ub09c \ub0b4\uc6a9\uc744 \ub2f4\uace0 \uc788\ub294 JavaDoc\uc744 \ub9ce\uc774 \ubcf4\uc544 \uc654\uc2b5\ub2c8\ub2e4. \uc798\ubabb\ub41c JavaDoc\uc740 \uc0ac\ub0b4 \uc18c\ud504\ud2b8\uc6e8\uc5b4\uc758 \ud488\uc9c8\uc5d0 \uc2ec\uac01\ud55c \uc601\ud5a5\uc744 \uc8fc\ubbc0\ub85c, \ub2e4\uc74c\uc758 \ud301\uc744 \uc774\ud574\ud558\uace0 \uc0ac\uc6a9\ud55c\ub2e4\uba74 \uc5ec\ub7ec\ubd84 \ud504\ub85c\uc81d\ud2b8\uc758 \uc9c8\uc744 \ub180\ub78d\uac8c \ud5a5\uc0c1\uc2dc\ud0ac \uac83\uc785\ub2c8\ub2e4.<\/p>\n
\n@link<\/tt> tag creates a link to an other type. I always prefer to use @link<\/tt> tag rather than not using it because it’s robust to refactoring (i.e. renaming classes also changes JavaDoc). @linkplain<\/tt> is also useful when you prefer a text link with a variable width font.<\/p>\n
@link<\/tt> \ud0dc\uadf8\ub294 \ub2e4\ub978 \ud0c0\uc784\uc73c\ub85c\uc758 \ub9c1\ud06c\ub97c \ub9cc\ub4ed\ub2c8\ub2e4. \uc800\ub294 \ud56d\uc0c1 @link<\/tt> \ud0dc\uadf8\ub97c \uc4f0\uc9c0 \uc54a\ub294 \uac83 \ubcf4\ub2e4\ub294 \uc4f0\ub294 \uac83\uc744 \uc120\ud638\ud558\ub294\ub370\uc694, \ub9ac\ud329\ud130\ub9c1\ud560 \ub54c JavaDoc\uc5d0 \uc801\uc5b4 \ub193\uc740 \ud074\ub798\uc2a4 \uc774\ub984\uc774 \uae68\uc9c0\uc9c0 \uc54a\uc544\uc11c\uc785\ub2c8\ub2e4. @linkplain<\/tt> \ub610\ud55c \uace0\uc815\ud3ed \ud14d\uc2a4\ud2b8 \ub9c1\ud06c\ubcf4\ub2e4\ub294 \uac00\ubcc0\ud3ed \ud14d\uc2a4\ud2b8 \ub9c1\ud06c\ub97c \uc4f0\uace0 \uc2f6\uc744 \ub54c \uc720\uc6a9\ud569\ub2c8\ub2e4.<\/p>\n \njavadoc<\/tt> detects an HTML file named as ‘package-info.html<\/tt>‘ in each package directory, and integrates its content into the generated JavaDoc. Here’s my template.<\/p>\n javadoc<\/tt>\uc740 \uac01 \ud328\ud0a4\uc9c0 \ub514\ub809\ud1a0\ub9ac\uc758 ‘package-info.html<\/tt>‘ HTML \ud30c\uc77c\uc744 \ucc3e\uc544 \uc0dd\uc131\ub420 JavaDoc \ub0b4\uc6a9\uc5d0 \ud1b5\ud569\uc2dc\ud0b5\ub2c8\ub2e4. \ub2e4\uc74c\uc740 \uc81c\uac00 \uc4f0\ub294 \ud15c\ud50c\ub9bf\uc785\ub2c8\ub2e4.<\/p>\n \nSince Java 5, you can put package-info.java<\/tt> instead of package-info.html<\/tt>. What is the advantage BTW? It’s in that you can specify package annotation.<\/p>\n Java 5\ubd80\ud130\ub294 package-info.html<\/tt> \ub300\uc2e0 package-info.java<\/tt>\ub97c \ub123\uc744 \uc218 \uc788\uc2b5\ub2c8\ub2e4. \uadf8\ub7f0\ub370 \uc7a5\uc810\uc774 \ubb58\uae4c\uc694? \uc7a5\uc810\uc740 \ud328\ud0a4\uc9c0 \uc560\ub178\ud14c\uc774\uc158\uc744 \uc801\uc5b4 \uc904 \uc218 \uc788\ub2e4\ub294 \ub370 \uc788\uc2b5\ub2c8\ub2e4.<\/p>\n That’s all. No class definition. It’s a bad idea to define a class here.<\/p>\n \uc774\uac8c \ub2f5\ub2c8\ub2e4. \ud074\ub798\uc2a4 \uc815\uc758\ub294 \uc5c6\uc2b5\ub2c8\ub2e4. \uc5ec\uae30\uc5d0 \ud074\ub798\uc2a4\ub97c \uc815\uc758\ud558\ub294 \uac83\uc740 \uc88b\uc9c0 \uc54a\uc2b5\ub2c8\ub2e4.<\/p>\n \nNo more unreadable <<\/tt>s and ><\/tt>s!<\/p>\n \ub354\uc774\uc0c1 \uc77d\uae30 \uc5b4\ub824\uc6b4 <<\/tt>\uc640 ><\/tt>\ub97c \uc4f8 \ud544\uc694\uac00 \uc5c6\uc2b5\ub2c8\ub2e4!<\/p>\n \n@code<\/tt> tag is actually @literal<\/tt> + (<pre><\/tt> or <code><\/tt>).<\/p>\n @code<\/tt> \ud0dc\uadf8\ub294 \uc0ac\uc2e4 @literal<\/tt> + (<pre><\/tt> \ub610\ub294 <code><\/tt>) \uc785\ub2c8\ub2e4.<\/p>\n NOTE: JavaDoc doesn’t support multilined expression yet: Sun Bug Database<\/a>.<\/p>\n NOTE: \uc544\uc9c1 JavaDoc\uc774 \uc5ec\ub7ec \uc904\ub85c \ub098\ub220 \uc4f0\ub294 \uac83\uc744 \uc9c0\uc6d0\ud558\uc9c0 \uc54a\ub124\uc694: Sun Bug Database<\/a>.<\/p>\n \n@value<\/tt> tag inlines the value of the specified static constant field.<\/p>\n @value<\/tt> \ud0dc\uadf8\ub294 \uc8fc\uc5b4\uc9c4 static \uc0c1\uc218 \ud544\ub4dc\uc758 \uac12\uc744 \ubb38\uc11c\uc5d0 \ubcf5\uc0ac\ud574 \ub123\uc5b4 \uc90d\ub2c8\ub2e4.<\/p>\n \nAccording to JavaDoc manual, it is a good practice to specify both a @deprecated<\/tt> tag (to specify a reason) and a @Deprecated<\/tt> annotation (for a compiler), though I don’t know why they had to introduce the annotation part.<\/p>\n JavaDoc \ub9e4\ub274\uc5bc\uc5d0 \ub530\ub974\uba74 @deprecated<\/tt> \ud0dc\uadf8 (\uc774\uc720\ub97c \uc124\uba85\ud558\uae30 \uc704\ud574)\uc640 @Deprecated<\/tt> \uc560\ub178\ud14c\uc774\uc158 (\ucef4\ud30c\uc77c\ub7ec\ub97c \uc704\ud574)\uc744 \ub458 \ub2e4 \uc4f0\ub294 \uac83\uc774 \uc88b\ub2e4\uace0 \ud569\ub2c8\ub2e4. \uc65c \uc560\ub178\ud14c\uc774\uc158\uc744 \ub9cc\ub4e4\uc5b4\uc57c \ud588\uc5c8\ub294\uc9c0\ub294 \uc798 \ubaa8\ub974\uaca0\uc9c0\ub9cc\uc694.<\/p>\n JavaDoc\uc5d0 \ub300\ud55c \uba87 \uac00\uc9c0 \ud301 It’s another Java 5-ish post which might not attract people, yet is very important. I find a lot of wrong or out-of-date JavaDoc due to lack of understandings on useful JavaDoc tags. Bad JavaDoc affects the quality of in-house softwares seriously, so knowing and using the following tips will improve… Continue reading \n
\/**
\n * Creates a new {@link Element} with the
\n * specified name.
\n *\/<\/pre>\n<\/blockquote>\npackage.html<\/tt> (or package-info.html<\/tt>)<\/h3>\n
\n
<!DOCTYPE HTML PUBLIC
\n \"-\/\/W3C\/\/DTD HTML 3.2 Final\/\/EN\">
\n<html>
\n<head>
\n<\/head>
\n<body>
\nThe first sentence is copied to the top of the
\nclass list in the generated JavaDoc. From here,
\nit's displayed after the generated class list.
\n...
\n<\/body>
\n<\/html><\/pre>\n<\/blockquote>\npackage-info.java<\/tt> (New in Java 5)<\/h3>\n
\n
\/**
\n * The first sentence is copied to the top of the
\n * class list in the generated JavaDoc. From
\n * here, it's displayed after the generated class
\n * list.
\n *\/
\n@Annotation1
\n@Annotation2
\n...
\npackage org.apache.mina.common;<\/pre>\n<\/blockquote>\n@literal<\/tt> tag (New in Java 5)<\/h3>\n
\n
\/**
\n * Returns true when
\n * {@literal the specified value < 3}.
\n *\/<\/pre>\n<\/blockquote>\n@code<\/tt> tag (New in Java 5)<\/h3>\n
\n
\/**
\n * Returns {@code true} when something cool
\n * happened.
\n * {@code
\n * multilined expression
\n * is also fine.
\n * }
\n *\/<\/pre>\n<\/blockquote>\n@value<\/tt> tag (Better in Java 5)<\/h3>\n
\n
\/**
\n * Sets the property X. If an invalid value is
\n * specified, it's set to the default value,
\n * {@value Constants#DEFAULT_X}).
\n *\/<\/pre>\n<\/blockquote>\n@deprecated<\/tt> tag and @Deprecated<\/tt> annotation<\/h3>\n
\n
\/**
\n * @deprecated This method has been deprecated
\n * since 1.0 because it performs a
\n * unsafe operation that breaks data
\n * integrity.
\n *\/
\n@Deprecated<\/pre>\n<\/blockquote>\n","protected":false},"excerpt":{"rendered":"