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 |
---|---|---|---|---|
@author |
<author>[value]</author> |
No |
No |
The author tag tends to help who is responsible for a class or method. |
@version |
<version>[value]</version> |
No |
No |
The version tag defines the version of the method. |
@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. |
@return |
<returns>[desc]</returns> |
Yes |
Yes |
Only for methods that have a return value. This is a good place to |
@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 |
|
<value>[desc]</value> |
Yes |
Yes |
Describes what the property [value] represents. |
|
<permission cref="[Member]" /> |
No |
Yes |
Notes the access level of a type or member. |
@see |
<seealso cref="[Member]" /> |
No |
Yes |
This links documentation that would beneficial in viewing in the relation |
{@link ref} |
<see cref="[Member]" /> |
Yes |
Yes |
This will create a link for the specified member. The cref part of this |
{@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, |
@since |
<since>[value]</since> |
No |
No |
This describes that this functionality was supported starting in version x. |
@serial |
|
No |
Unsure |
[Serializable] - Sandcastle could use the [Serializable] attribute to |
@deprecated |
|
No |
Yes |
[Obsolete] - Sandcastle / SHFB does make use of the [Obsolete] |
|
<summary>[desc]<summary> |
Yes |
Yes |
Give a brief overview about a class, namespace or member does |
|
<remarks>[xml]</remarks> |
Yes |
Yes |
Give the full explanation of what class, namespace or member does |
|
<example>[xml]</example> |
No |
Yes |
Denotes a full section targeted towards providing an example in the |
[<p />] |
<para>[text]</para> |
Yes |
Yes |
This should always be used for paragraphs inside of the <remarks /> |
<code /> |
<c>[Type|value]</c> |
Yes |
Yes |
Instructs Sandcastle to format the text as code. examples: <c>null</c>, |
<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. |
|
<include file="[filepath]" |
No |
Yes |
This element will let you include documentation from another file and |
|
<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>