Documentation Goals
- Convert all the Java Doc syntax is converted to their XML Doc Comment equivalent.
- There should be no warnings from the vs/mono compiler from XML comments.
- Fix spelling & grammar mistakes.
- Make sure the existing documentation is understandable.
- Validate what the end result looks like in Sandcastle, Microsoft's replacement for NDoc.
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="7c9aea24-42fe-45a1-abff-c1d64463dd1f"><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="b9ca8810-c3aa-4ac4-a63d-521970f06dcf"><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="79d1cb50-fee7-461a-8358-2d22c8b74fe8"><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="dcf45210-666e-4cf1-a1c6-8b9b5d153acf"><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="d15d6ae2-87df-45f4-9f9c-7782004ddf78"><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="1d7f83c2-e73c-49ac-9eb6-de990acf96f5"><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="a07b7ed7-40ba-47e6-a1ef-48b606a428fe"><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="1f6142eb-dbf4-45bd-bb9d-76fb20814a79"><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="2dcc0cf2-5ab5-425f-ab98-1b782f1ce244"><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="a2609e6c-9637-44b3-9a07-db284fee6ecd"><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="bc48d2e5-42b5-4b2e-b9ee-0f6b6a4c7f73"><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="72a7e4e1-efd1-4458-969d-8ca35d968026"><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="de8a0f37-0ab7-45e1-ac8e-1559b55bd46f"><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="091f3edc-66b8-4419-bb3f-88a692574083"><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="1ca9a6d6-516e-47f2-903e-f90a77db238f"><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="b1bc33a4-e434-483f-9268-a191a2cc9cd4"><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="7a90799f-d165-43b1-85f9-d65640e8832b"><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="3a4790f2-8535-49ba-bd25-6620b53b88df"><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="9140054e-71bc-466e-b5d1-4d17b69f162d"><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="10614116-0a7a-4cb3-be3f-682e131cabf2"><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
- Recommended Tags For Documentation Comments
- Sandcastle on Codeplex
- http://shfb.codeplex.com/Sandcastle Help File Builder
- GhostDoc
Example of Converting JavaDoc into XML Doc Comments
These samples were taken from the v2.9.4 version of the TokenStream class found under the Lucene.Net.Analyis namespace.
Java Docs - implementToken()
/** * 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> */
Xml Doc Comments - ImplementToken()
/// <summary> /// Consumers, like <see cref="Lucene.Net.Index.IndexWriter"/>, use this /// method to advance the stream to the next token. Implementing classes must /// implement this method and update the appropriate <see cref="Lucene.Net.Util.AttributeImpl"/>s /// with the attributes of the next token. /// </summary> /// <remarks> /// <para> /// 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 /// <see cref="AttributeSource.CaptureState()"/> to create a copy of the /// current attribute state. /// </para> /// <para> /// This method is called for every token of a document, so an efficient /// implementation is crucial for good performance. To avoid calls to /// <see cref="AttributeSource.AddAttribute(Type)"/> and <see cref="AttributeSource.GetAttribute(Type)"/> or downcasts, /// references to all <see cref="AttributeImpl" />s that this stream uses should be /// retrieved during instantiation. /// </para> /// <para> /// 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 /// <see cref="IncrementToken()" />. /// </para> /// <note> /// This method will be abstract in version 3.0 /// </note> /// </remarks> /// <returns> <c>true</c> if the end of the stream has <b>not</b> reached, otherwise <c>false</c>. </returns>