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="098b1839-ebef-491f-80ce-4b2c346c25f6"><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="4b8277c2-5b8e-4284-bb58-2a88875118cf"><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="1db8a09a-cb1b-4f65-b63b-51d90dd33e87"><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="375c2959-2901-4606-abbc-a4b07552b8da"><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="45beccda-67dc-4fbf-b19b-528390cb7b2a"><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="2cc68cf7-9076-4727-be29-f340b19e1ca5"><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="61d16f94-a08c-48ef-9c91-dd5f32ee5e6f"><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="22f4dc48-6632-4f4e-9953-f7921940b753"><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="49cb8d1a-c701-4d15-bf9f-26eab34a3edc"><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="15398cff-d331-41ce-98b5-15c07dbebf01"><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="141a5e1f-b0bb-4ed8-817d-864a08bc3969"><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="3650619c-487e-40a2-89fa-d766323ac556"><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="f0b5ac59-ddd2-4ae4-b414-54a3b606d0e3"><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="2883496b-8830-44bc-8bc5-743b6e556885"><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="cc32cb74-11df-444d-aa18-cd75fb687d59"><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="b3ff8b37-9bc7-4cba-85bd-b8e766a098e3"><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="ec1fc826-d7c6-4c68-9488-17d94f114cd2"><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="f2ba6f30-927f-4731-ba63-7a0e5155f757"><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="d797515f-31c6-4e93-854b-91f6839acccf"><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="b6c3f593-f90d-4cb4-b4fe-80931f2c3ac5"><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>