...
XML Doc Comments Guide
TODO
JavaDoc & XML Doc Comments
...
Equivalents
- Supported? means is it supported by sandcastle or SHFB
...
Java Doc Tag | XML Doc Comments Element | Required | Supported?* | Description | ||
---|---|---|---|---|---|---|
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="6643832a-925d-4200-b47b-e4302b635d16"><ac:plain-text-body><![CDATA[ | @author | <author>[value]</author> | No | No | The author tag tends to help who is responsible for a class or method. | |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="39455c1b-d563-43b7-acd9-8f26ef20db57"><ac:plain-text-body><![CDATA[ | @version | <version>[value]</version> | No | No | The version tag defines the version of the method. | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="7858c92d-a1d8-40d5-a48e-ad8295b83980"><ac:plain-text-body><![CDATA[ | @param | <param name="">[desc]</para> | Yes | Yes | Describes a parameter in a method signature. This is often | |
| <typeparam name=""> | Yes | Yes | Describes a generic type parameter. | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="6b2ebd1c-cccc-4627-88d7-405e6d9bae3b"><ac:plain-text-body><![CDATA[ | @return | <returns>[desc]</returns> | Yes | Yes | Only for methods that have a return value. This is a good place to | |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="e4405425-6a5e-486a-bfc9-5a84fc5699c4"><ac:plain-text-body><![CDATA[ | @throws | <exception cref="[Type]"> | No | Yes | This denotes when a class method or property can throw an exception | |
@exception | <exception cref=""> | No | Yes | Same as above | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="fc2f76ea-7bcf-44c2-9a7e-2cb7a461830c"><ac:plain-text-body><![CDATA[ |
| <value>[desc]</value> | Yes | Yes | Describes what the property [value] represents. | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="ee533aa8-dfa2-4ff8-9a77-28b0cfd92e20"><ac:plain-text-body><![CDATA[ |
| <permission cref="[Member]" /> | No | Yes | Notes the access level of a type or member. | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="f1db88a5-a9a5-44dd-bdd6-791b36b94a24"><ac:plain-text-body><![CDATA[ | @see | <seealso cref="[Member]" /> | No | Yes | This links documentation that would beneficial in viewing in the relation | |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="7f07a6c0-8d21-41fb-ac69-cb28d5c675e2"><ac:plain-text-body><![CDATA[ | {@link ref} | <see cref="[Member]" /> | Yes | Yes | This will create a link for the specified member. The cref part of this | |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="df455a7a-a908-4494-ab98-83a67f50ac15"><ac:plain-text-body><![CDATA[ | {@link ref} | <paramref name="[Member]" /> | Yes | Yes | Inline element that references a parameter of the method, typically | |
{@link ref} | <typeparamref | Yes | Yes | Inline element that references a generic type parameter of the method, | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="d3d197e2-d3db-470c-8ae2-3c15a08e4dcb"><ac:plain-text-body><![CDATA[ | @since | <since>[value]</since> | No | No | This describes that this functionality was supported starting in version x. | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="2f88c6c3-aae6-4a26-8fd2-7e8e1679475d"><ac:plain-text-body><![CDATA[ | @serial |
| No | Unsure | [Serializable] - Sandcastle could use the [Serializable] attribute to | |
@deprecated |
| No | Yes | [Obsolete] - Sandcastle / SHFB does make use of the [Obsolete] | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="913e84e4-8da3-41e3-9105-3088723f1263"><ac:plain-text-body><![CDATA[ |
| <summary>[desc]<summary> | Yes | Yes | Give a brief overview about a class, namespace or member does | |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="a2078820-261d-4ada-81f7-0049e443ede9"><ac:plain-text-body><![CDATA[ |
| <remarks>[xml]</remarks> | Yes | Yes | Give the full explanation of what class, namespace or member does | |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="8ff07f5d-5f98-4ecb-84d4-1048b5ac27d7"><ac:plain-text-body><![CDATA[ |
| <example>[xml]</example> | No | Yes | Denotes a full section targeted towards providing an example in the | |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="13cd3284-7f89-4de6-835f-9eba79d7ca83"><ac:plain-text-body><![CDATA[ | [<p />] | <para>[text]</para> | Yes | Yes | This should always be used for paragraphs inside of the <remarks /> | |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="65078fea-8197-466e-bc5b-7100649dbe41"><ac:plain-text-body><![CDATA[ | <code /> | <c>[Type|value]</c> | Yes | Yes | Instructs Sandcastle to format the text as code. examples: <c>null</c>, | |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="cdb7cd0b-1550-4623-9e4f-0323571eda49"><ac:plain-text-body><![CDATA[ | <code /> | <code lang="[lang]"> | No | Yes | This element specifies a code example. | |
<ul>,<ol> | <list> | Yes | Yes | When creating a list, you should use the <list> element. However SHFB | ||
<li> | <item> | Yes | Yes | When creating a list item, you should use the <item> element. | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="618203f8-a19c-4eb4-80d4-a4beec540b26"><ac:plain-text-body><![CDATA[ |
| <include file="[filepath]" | No | Yes | This element will let you include documentation from another file and | |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="8822dce3-4260-4dd2-add9-e985a4db3ba7"><ac:plain-text-body><![CDATA[ |
| <note>[xml|text]</note> | No | Yes | Nonstandard. This tag is supported by SHFB and possibly even | |
| <inheritdoc /> | No | Yes | Nonstandard. This tag is supported by SHFB. This will specify SHFB |
XML Doc Comments References
...
Code Block |
---|
/** * Consumers (i.e., {@link IndexWriter}) use this method to advance the stream to * the next token. Implementing classes must implement this method and update * the appropriate {@link AttributeImpl}s with the attributes of the next * token. * <P> * The producer must make no assumptions about the attributes after the method * has been returned: the caller may arbitrarily change it. If the producer * needs to preserve the state for subsequent calls, it can use * \{@link #captureState} to create a copy of the current attribute state. * <p> * This method is called for every token of a document, so an efficient * implementation is crucial for good performance. To avoid calls to * {@link #addAttribute(Class)} and {@link #getAttribute(Class)} or downcasts, * references to all {@link AttributeImpl}s that this stream uses should be * retrieved during instantiation. * <p> * To ensure that filters and consumers know which attributes are available, * the attributes must be added during instantiation. Filters and consumers * are not required to check for availability of attributes in * {@link #incrementToken()}. * * @return false for end of stream; true otherwise * * <p> * <b>Note that this method will be defined abstract in Lucene * 3.0.</b> */ |
...