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()
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> */ |
Xml Doc Comments - ImplementToken()
Code Block | ||||
---|---|---|---|---|
| ||||
/// <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> |