(window.webpackJsonp=window.webpackJsonp||[]).push([[1558],{1966:function(e,a,t){"use strict";t.r(a);var n=t(31),s=Object(n.a)({},(function(){var e=this,a=e.$createElement,t=e._self._c||a;return t("ContentSlotsDistributor",{attrs:{"slot-key":e.$parent.slotKey}},[t("h1",{attrs:{id:"documenting-java-code"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#documenting-java-code"}},[e._v("#")]),e._v(" Documenting Java Code")]),e._v(" "),t("p",[e._v("Documentation for java code is often generated using "),t("a",{attrs:{href:"http://www.oracle.com/technetwork/articles/java/index-jsp-135444.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("javadoc"),t("OutboundLink")],1),e._v(". Javadoc was created by Sun Microsystems for the purpose of "),t("a",{attrs:{href:"https://en.wikipedia.org/wiki/Javadoc",target:"_blank",rel:"noopener noreferrer"}},[e._v("generating API documentation"),t("OutboundLink")],1),e._v(" in HTML format from java source code. Using the HTML format gives the convenience of being able to hyperlink related documents together.")]),e._v(" "),t("h2",{attrs:{id:"class-documentation"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#class-documentation"}},[e._v("#")]),e._v(" Class Documentation")]),e._v(" "),t("p",[e._v("All Javadoc comments begin with a block comment followed by an asterisk ("),t("code",[e._v("/**")]),e._v(") and end when the block comment does ("),t("code",[e._v("*/")]),e._v(").  Optionally, each line can begin with arbitrary whitespace and a single asterisk; these are ignored when the documentation files are generated.")]),e._v(" "),t("div",{staticClass:"language-java extra-class"},[t("pre",{pre:!0,attrs:{class:"language-java"}},[t("code",[t("span",{pre:!0,attrs:{class:"token comment"}},[e._v('/**\n * Brief summary of this class, ending with a period.\n *\n * It is common to leave a blank line between the summary and further details.\n * The summary (everything before the first period) is used in the class or package \n * overview section.\n *\n * The following inline tags can be used (not an exhaustive list): \n * {@link some.other.class.Documentation} for linking to other docs or symbols\n * {@link some.other.class.Documentation Some Display Name} the link\'s appearance can be \n * customized by adding a display name after the doc or symbol locator\n * {@code code goes here} for formatting as code\n * {@literal <>[]()foo} for interpreting literal text without converting to HTML markup \n * or other tags.\n *\n * Optionally, the following tags may be used at the end of class documentation \n * (not an exhaustive list):\n *\n * @author John Doe\n * @version 1.0\n * @since 5/10/15\n * @see some.other.class.Documentation\n * @deprecated This class has been replaced by some.other.package.BetterFileReader\n * \n * You can also have custom tags for displaying additional information.\n * Using the @custom.<NAME> tag and the -tag custom.<NAME>:htmltag:"context"\n * command line option, you can create a custom tag.\n *\n * Example custom tag and generation:\n * @custom.updated 2.0    \n * Javadoc flag: -tag custom.updated:a:"Updated in version:"\n * The above flag will display the value of @custom.updated under "Updated in version:"\n *\n */')]),e._v("\n"),t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("public")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("class")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token class-name"}},[e._v("FileReader")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("{")]),e._v("\n"),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("}")]),e._v("\n\n")])])]),t("p",[e._v("The same tags and format used for "),t("code",[e._v("Classes")]),e._v(" can be used for "),t("code",[e._v("Enums")]),e._v(" and "),t("code",[e._v("Interfaces")]),e._v(" as well.")]),e._v(" "),t("h2",{attrs:{id:"method-documentation"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#method-documentation"}},[e._v("#")]),e._v(" Method Documentation")]),e._v(" "),t("p",[e._v("All Javadoc comments begin with a block comment followed by an asterisk ("),t("code",[e._v("/**")]),e._v(") and end when the block comment does ("),t("code",[e._v("*/")]),e._v("). Optionally, each line can begin with arbitrary whitespace and a single asterisk; these are ignored when the documentation files are generated.")]),e._v(" "),t("div",{staticClass:"language-java extra-class"},[t("pre",{pre:!0,attrs:{class:"language-java"}},[t("code",[t("span",{pre:!0,attrs:{class:"token comment"}},[e._v("/**\n * Brief summary of method, ending with a period.\n *\n * Further description of method and what it does, including as much detail as is \n * appropriate.  Inline tags such as\n * {@code code here}, {@link some.other.Docs}, and {@literal text here} can be used.\n *\n * If a method overrides a superclass method, {@inheritDoc} can be used to copy the \n * documentation\n * from the superclass method\n *\n * @param stream Describe this parameter.  Include as much detail as is appropriate\n *               Parameter docs are commonly aligned as here, but this is optional.\n *               As with other docs, the documentation before the first period is \n *               used as a summary.\n *\n * @return Describe the return values.  Include as much detail as is appropriate\n *         Return type docs are commonly aligned as here, but this is optional.\n *         As with other docs, the documentation before the first period is used as a \n *         summary.\n *\n * @throws IOException Describe when and why this exception can be thrown.\n *                     Exception docs are commonly aligned as here, but this is \n *                     optional.\n *                     As with other docs, the documentation before the first period \n *                     is used as a summary.\n *                     Instead of @throws, @exception can also be used.\n *\n * @since 2.1.0\n * @see some.other.class.Documentation\n * @deprecated  Describe why this method is outdated. A replacement can also be specified.\n */")]),e._v("\n"),t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("public")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token class-name"}},[e._v("String")]),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("[")]),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("]")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token function"}},[e._v("read")]),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("(")]),t("span",{pre:!0,attrs:{class:"token class-name"}},[e._v("InputStream")]),e._v(" stream"),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v(")")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("throws")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token class-name"}},[e._v("IOException")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("{")]),e._v("\n    "),t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("return")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("null")]),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v(";")]),e._v("\n"),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("}")]),e._v("\n\n")])])]),t("h2",{attrs:{id:"package-documentation"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#package-documentation"}},[e._v("#")]),e._v(" Package Documentation")]),e._v(" "),t("p",[e._v("It is possible to create package-level documentation in Javadocs using a file called "),t("code",[e._v("package-info.java")]),e._v(".  This file must be formatted as below. Leading whitespace and asterisks optional, typically present in each line for formatting reason")]),e._v(" "),t("div",{staticClass:"language-java extra-class"},[t("pre",{pre:!0,attrs:{class:"language-java"}},[t("code",[t("span",{pre:!0,attrs:{class:"token comment"}},[e._v("/**\n * Package documentation goes here; any documentation before the first period will \n * be used as a summary.\n *\n * It is common practice to leave a blank line between the summary and the rest\n * of the documentation; use this space to describe the package in as much detail\n * as is appropriate.\n * \n * Inline tags such as {@code code here}, {@link reference.to.other.Documentation},\n * and {@literal text here} can be used in this documentation.\n */")]),e._v("\n"),t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("package")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token namespace"}},[e._v("com"),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v(".")]),e._v("example"),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v(".")]),e._v("foo")]),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v(";")]),e._v("\n\n"),t("span",{pre:!0,attrs:{class:"token comment"}},[e._v("// The rest of the file must be empty.")]),e._v("\n\n")])])]),t("p",[e._v("In the above case, you must put this file "),t("code",[e._v("package-info.java")]),e._v(" inside the folder of the Java package "),t("code",[e._v("com.example.foo")]),e._v(".")]),e._v(" "),t("h2",{attrs:{id:"building-javadocs-from-the-command-line"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#building-javadocs-from-the-command-line"}},[e._v("#")]),e._v(" Building Javadocs From the Command Line")]),e._v(" "),t("p",[e._v("Many IDEs provide support for generating HTML from Javadocs automatically; some build tools ("),t("a",{attrs:{href:"https://maven.apache.org/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Maven"),t("OutboundLink")],1),e._v(" and "),t("a",{attrs:{href:"https://gradle.org/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Gradle"),t("OutboundLink")],1),e._v(", for example) also have plugins that can handle the HTML creation.")]),e._v(" "),t("p",[e._v("However, these tools are not required to generate the Javadoc HTML; this can be done using the command line "),t("code",[e._v("javadoc")]),e._v(" tool.")]),e._v(" "),t("p",[e._v("The most basic usage of the tool is:")]),e._v(" "),t("div",{staticClass:"language-java extra-class"},[t("pre",{pre:!0,attrs:{class:"language-java"}},[t("code",[e._v("javadoc "),t("span",{pre:!0,attrs:{class:"token class-name"}},[e._v("JavaFile")]),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v(".")]),e._v("java\n\n")])])]),t("p",[e._v("Which will generate HTML from the Javadoc comments in "),t("code",[e._v("JavaFile.java")]),e._v(".")]),e._v(" "),t("p",[e._v("A more practical use of the command line tool, which will recursively read all java files in "),t("code",[e._v("[source-directory]")]),e._v(", create documentation for "),t("code",[e._v("[package.name]")]),e._v(" and all sub-packages, and place the generated HTML in the "),t("code",[e._v("[docs-directory]")]),e._v(" is:")]),e._v(" "),t("div",{staticClass:"language-java extra-class"},[t("pre",{pre:!0,attrs:{class:"language-java"}},[t("code",[e._v("javadoc "),t("span",{pre:!0,attrs:{class:"token operator"}},[e._v("-")]),e._v("d "),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("[")]),e._v("docs"),t("span",{pre:!0,attrs:{class:"token operator"}},[e._v("-")]),e._v("directory"),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("]")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token operator"}},[e._v("-")]),e._v("subpackages "),t("span",{pre:!0,attrs:{class:"token operator"}},[e._v("-")]),e._v("sourcepath "),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("[")]),e._v("source"),t("span",{pre:!0,attrs:{class:"token operator"}},[e._v("-")]),e._v("directory"),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("]")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("[")]),t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("package")]),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v(".")]),e._v("name"),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("]")]),e._v("\n\n")])])]),t("h2",{attrs:{id:"links"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#links"}},[e._v("#")]),e._v(" Links")]),e._v(" "),t("p",[e._v("Linking to other Javadocs is done with the "),t("code",[e._v("@link")]),e._v(" tag:")]),e._v(" "),t("div",{staticClass:"language-java extra-class"},[t("pre",{pre:!0,attrs:{class:"language-java"}},[t("code",[t("span",{pre:!0,attrs:{class:"token comment"}},[e._v("/**\n * You can link to the javadoc of an already imported class using {@link ClassName}.\n *\n * You can also use the fully-qualified name, if the class is not already imported: \n *  {@link some.other.ClassName}\n *\n * You can link to members (fields or methods) of a class like so:\n *  {@link ClassName#someMethod()}\n *  {@link ClassName#someMethodWithParameters(int, String)}\n *  {@link ClassName#someField}\n *  {@link #someMethodInThisClass()} - used to link to members in the current class\n *  \n * You can add a label to a linked javadoc like so:\n *  {@link ClassName#someMethod() link text} \n */")]),e._v("\n\n")])])]),t("p",[t("a",{attrs:{href:"https://i.stack.imgur.com/3A3cX.png",target:"_blank",rel:"noopener noreferrer"}},[t("img",{attrs:{src:"https://i.stack.imgur.com/3A3cX.png",alt:"screen capture of first example"}}),t("OutboundLink")],1)]),e._v(" "),t("p",[e._v("With the "),t("code",[e._v("@see")]),e._v(" tag you can add elements to the "),t("strong",[e._v("See also")]),e._v(" section. Like "),t("code",[e._v("@param")]),e._v(" or "),t("code",[e._v("@return")]),e._v(" the place where they appear is not relevant. The spec says you should write it after "),t("code",[e._v("@return")]),e._v(".")]),e._v(" "),t("div",{staticClass:"language-java extra-class"},[t("pre",{pre:!0,attrs:{class:"language-java"}},[t("code",[t("span",{pre:!0,attrs:{class:"token comment"}},[e._v("/**\n * This method has a nice explanation but you might found further\n * information at the bottom.\n *\n * @see ClassName#someMethod()\n */")]),e._v("\n\n")])])]),t("p",[t("a",{attrs:{href:"https://i.stack.imgur.com/WxxAT.png",target:"_blank",rel:"noopener noreferrer"}},[t("img",{attrs:{src:"https://i.stack.imgur.com/WxxAT.png",alt:"screen capture of example"}}),t("OutboundLink")],1)]),e._v(" "),t("p",[e._v("If you want to add "),t("strong",[e._v("links to external resources")]),e._v(" you can just use the HTML "),t("code",[e._v("<a>")]),e._v(" tag. You can use it inline anywhere or inside both "),t("code",[e._v("@link")]),e._v(" and "),t("code",[e._v("@see")]),e._v(" tags.")]),e._v(" "),t("div",{staticClass:"language-java extra-class"},[t("pre",{pre:!0,attrs:{class:"language-java"}},[t("code",[t("span",{pre:!0,attrs:{class:"token comment"}},[e._v('/**\n * Wondering how this works? You might want\n * to check this <a href="proxy.php?url=http%3A%2F%2Fstackoverflow.com%2F">great service</a>.\n *\n * @see <a href="proxy.php?url=http%3A%2F%2Fstackoverflow.com%2F">Stack Overflow</a>\n */')]),e._v("\n\n")])])]),t("p",[t("a",{attrs:{href:"https://i.stack.imgur.com/VyrDF.png",target:"_blank",rel:"noopener noreferrer"}},[t("img",{attrs:{src:"https://i.stack.imgur.com/VyrDF.png",alt:"screen capture of external link example"}}),t("OutboundLink")],1)]),e._v(" "),t("h2",{attrs:{id:"field-documentation"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#field-documentation"}},[e._v("#")]),e._v(" Field Documentation")]),e._v(" "),t("p",[e._v("All Javadoc comments begin with a block comment followed by an asterisk ("),t("code",[e._v("/**")]),e._v(") and end when the block comment does ("),t("code",[e._v("*/")]),e._v("). Optionally, each line can begin with arbitrary whitespace and a single asterisk; these are ignored when the documentation files are generated.")]),e._v(" "),t("div",{staticClass:"language-java extra-class"},[t("pre",{pre:!0,attrs:{class:"language-java"}},[t("code",[t("span",{pre:!0,attrs:{class:"token comment"}},[e._v("/**\n * Fields can be documented as well.\n * \n * As with other javadocs, the documentation before the first period is used as a\n * summary, and is usually separated from the rest of the documentation by a blank \n * line.\n * \n * Documentation for fields can use inline tags, such as:\n * {@code code here}\n * {@literal text here}\n * {@link other.docs.Here}\n * \n * Field documentation can also make use of the following tags:\n * \n * @since 2.1.0\n * @see some.other.class.Documentation\n * @deprecated Describe why this field is outdated\n */")]),e._v("\n"),t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("public")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("static")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("final")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token class-name"}},[e._v("String")]),e._v(" CONSTANT_STRING "),t("span",{pre:!0,attrs:{class:"token operator"}},[e._v("=")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token string"}},[e._v('"foo"')]),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v(";")]),e._v("\n\n")])])]),t("h2",{attrs:{id:"code-snippets-inside-documentation"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#code-snippets-inside-documentation"}},[e._v("#")]),e._v(" Code snippets inside documentation")]),e._v(" "),t("p",[e._v("The canonical way of writing code inside documentation is with the "),t("code",[e._v("{@code }")]),e._v(" construct. If you have multiline code wrap inside "),t("code",[e._v("<pre></pre>")]),e._v(".")]),e._v(" "),t("div",{staticClass:"language-java extra-class"},[t("pre",{pre:!0,attrs:{class:"language-java"}},[t("code",[t("span",{pre:!0,attrs:{class:"token comment"}},[e._v('/**\n * The Class TestUtils.\n * <p>\n * This is an {@code inline("code example")}.\n * <p>\n * You should wrap it in pre tags when writing multiline code.\n * <pre>{@code\n *  Example example1 = new FirstLineExample();\n *  example1.butYouCanHaveMoreThanOneLine();\n * }</pre>\n * <p>\n * Thanks for reading.\n */')]),e._v("\n"),t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("class")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token class-name"}},[e._v("TestUtils")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("{")]),e._v("\n\n")])])]),t("p",[e._v("Sometimes you may need to put some complex code inside the javadoc comment. The "),t("code",[e._v("@")]),e._v(" sign is specially problematic. The use of the old "),t("code",[e._v("<code>")]),e._v(" tag alongside the "),t("code",[e._v("{@literal }")]),e._v(" construct solves the problem.")]),e._v(" "),t("div",{staticClass:"language-java extra-class"},[t("pre",{pre:!0,attrs:{class:"language-java"}},[t("code",[t("span",{pre:!0,attrs:{class:"token comment"}},[e._v('/**\n * Usage:\n * \n```java\n\n * class SomethingTest {\n * {@literal @}Rule\n *  public SingleTestRule singleTestRule = new SingleTestRule("test1");\n *\n * {@literal @}Test\n *  public void test1() {\n *      // only this test will be executed\n *  }\n *\n *  ...\n * }\n * \n')])])])]),t("p",[e._v("*/\nclass SingleTestRule implements TestRule { }")]),e._v(" "),t("div",{staticClass:"language- extra-class"},[t("pre",{pre:!0,attrs:{class:"language-text"}},[t("code",[e._v("\n\n\n## Inline Code Documentation\n\n\nApart from the Javadoc documentation code can be documented inline.\n\nSingle Line comments are started by `//` and may be positioned after a statement on the same line, but not before.\n\n```java\npublic void method() {\n  \n  //single line comment\n  someMethodCall(); //single line comment after statement\n  \n}\n\n")])])]),t("p",[e._v("Multi-Line comments are defined between "),t("code",[e._v("/*")]),e._v(" and "),t("code",[e._v("*/")]),e._v(". They can span multiple lines and may even been positioned between statements.")]),e._v(" "),t("div",{staticClass:"language-java extra-class"},[t("pre",{pre:!0,attrs:{class:"language-java"}},[t("code",[t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("public")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token keyword"}},[e._v("void")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token function"}},[e._v("method")]),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("(")]),t("span",{pre:!0,attrs:{class:"token class-name"}},[e._v("Object")]),e._v(" object"),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v(")")]),e._v(" "),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("{")]),e._v("\n  \n  "),t("span",{pre:!0,attrs:{class:"token comment"}},[e._v("/*\n    multi \n    line \n    comment\n  */")]),e._v("\n  object"),t("span",{pre:!0,attrs:{class:"token comment"}},[e._v("/*inner-line-comment*/")]),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v(".")]),t("span",{pre:!0,attrs:{class:"token function"}},[e._v("method")]),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("(")]),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v(")")]),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v(";")]),e._v(" \n"),t("span",{pre:!0,attrs:{class:"token punctuation"}},[e._v("}")]),e._v("\n\n")])])]),t("p",[e._v("JavaDocs are a special form of multi-line comments, starting with "),t("code",[e._v("/**")]),e._v(".")]),e._v(" "),t("p",[e._v("As too many inline comments may decrease readability of code, they should be used sparsely in case the code isn't self-explanatory enough or the design decision isn't obvious.")]),e._v(" "),t("p",[e._v("An additional use case for single-line comments is the use of TAGs, which are short, convention driven keywords. Some development environments recognize certain conventions for such single-comments. Common examples are")]),e._v(" "),t("ul",[t("li",[t("code",[e._v("//TODO")])]),e._v(" "),t("li",[t("code",[e._v("//FIXME")])])]),e._v(" "),t("p",[e._v("Or issue references, i.e. for Jira")]),e._v(" "),t("ul",[t("li",[t("code",[e._v("//PRJ-1234")])])]),e._v(" "),t("h4",{attrs:{id:"syntax"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#syntax"}},[e._v("#")]),e._v(" Syntax")]),e._v(" "),t("ul",[t("li",[e._v("/** -- start of JavaDoc on a class, field, method, or package")]),e._v(" "),t("li",[e._v("@author // To name the author of the class, interface or enum. It is required.")]),e._v(" "),t("li",[e._v("@version // The version of that class, interface or enum. It is required. You could use macros like %I% or %G% for you source control software to fill in on checkout.")]),e._v(" "),t("li",[e._v("@param // To show the arguments (parameters) of a method or a constructor. Specify one @param tag for each parameter.")]),e._v(" "),t("li",[e._v("@return // To show the return types for non-void methods.")]),e._v(" "),t("li",[e._v("@exception // Shows what exceptions could be thrown from the method or constructor. Exceptions that "),t("strong",[e._v("MUST")]),e._v(" be caught should be listed here. If you want, you can also include those that do not need to be caught, like ArrayIndexOutOfBoundsException. Specify one @exception for each exception that can be thrown.")]),e._v(" "),t("li",[e._v("@throws // Same as @exception.")]),e._v(" "),t("li",[e._v("@see // Links to a method, field, class or package. Use in the form of package.Class#something.")]),e._v(" "),t("li",[e._v("@since // When this method, field or class was added. For example, JDK-8 for a class like "),t("a",{attrs:{href:"https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("java.util.Optional"),t("T",[t("OutboundLink")],1)],1),e._v(".")]),e._v(" "),t("li",[e._v("@serial, @serialField, @serialData // Used to show the serialVersionUID.")]),e._v(" "),t("li",[e._v("@deprecated // To mark a class, method or field as deprecated. For example, one would be "),t("a",{attrs:{href:"https://docs.oracle.com/javase/8/docs/api/java/io/StringBufferInputStream.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("java.io.StringBufferInputStream"),t("OutboundLink")],1),e._v(". See a full list of existing deprecated classes "),t("a",{attrs:{href:"https://docs.oracle.com/javase/8/docs/api/deprecated-list.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("here"),t("OutboundLink")],1),e._v(".")]),e._v(" "),t("li",[e._v("{@link} // Similar to @see, but can be used with custom text: {@link #setDefaultCloseOperation(int closeOperation) see JFrame#setDefaultCloseOperation for more info}.")]),e._v(" "),t("li",[e._v("{@linkplain} // Similar to {@link}, but without the code font.")]),e._v(" "),t("li",[e._v("{@code} // For literal code, such as HTML tags. For example: {@code "),t("html"),e._v("}. However, this will use a monospaced font. To get the same result without the monospace font, use {@literal}.")]),e._v(" "),t("li",[e._v("{@literal} // Same as {@code}, but without the monospaced font.")]),e._v(" "),t("li",[e._v("{@value} // Shows the value of a static field: The value of JFrame#EXIT_ON_CLOSE is {@value}. Or, you could link to a certain field: Uses the app name {@value AppConstants#APP_NAME}.")]),e._v(" "),t("li",[e._v("{@docRoot} // The root folder of the JavaDoc HTML relative to the current file. Example: "),t("a",{attrs:{href:"{@docRoot}/credits.html"}},[e._v("Credits")]),e._v(".")]),e._v(" "),t("li",[e._v("HTML is allowed: "),t("code",[e._v('"Hi cookies".substring(3)')]),e._v(".")]),e._v(" "),t("li",[e._v("*/ -- end of JavaDoc declaration")])]),e._v(" "),t("h4",{attrs:{id:"remarks"}},[t("a",{staticClass:"header-anchor",attrs:{href:"#remarks"}},[e._v("#")]),e._v(" Remarks")]),e._v(" "),t("p",[e._v("Javadoc is a tool included with the JDK that allows in-code comments to be converted to an HTML documentation. The "),t("a",{attrs:{href:"https://docs.oracle.com/javase/8/docs/api/index.html?overview-summary.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("Java API Specification"),t("OutboundLink")],1),e._v(" was generated using Javadoc. The same is true for much of the documentation of 3rd-party libraries.")])])}),[],!1,null,null,null);a.default=s.exports}}]);