Documenting Lucene.Net

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

<c> vs <code> - <c> is used for references to code terms or values that are not being linked to another file in the documentation. i.e. <c>true</c> or <c>false>. <c>null</c>. Lets talk about the <c>TokenStream</c> class. JavaDoc will sometimes use the <code></code> tags, but that needs to be transformed into <c></c> tags for XML Doc Comments.
*<see cref=""> vs {@link indentifer }* - use the <see> tag in place of the {@link Identifier}. SandCastle and Visual Studio will sometimes be able to infer the Type just by the short class name. Other times it might require the full name which is the namespace & class name. For methods, include the parentheses, you will also need to include the types of each argument. {@link #getAttribute(Class)} in JavaDoc would be turned into <see cref="AttributeSource.GetAttribute(System.Type)" />
<exception cref="" /> vs @throws -- lists the possible exception. In JavaDoc it would @throws IOException. The xml version would be <exception cref="System.IO.IOException">[Not required description of why this would be thrown]</exception>
Obsolete vs @deprecated - Is notated by the Obsolete Attribute. JavaDoc uses @deprecated. There is not an XML equivalent, however SandCastle will make note of this for you, if your uses the Attribute.
<returns></returns> vs @return - Describe what the return object is.
<para></para> vs - Denotes a paragraph. The XML doc comments for whatever reason uses the longer form tag of <para>. If you see , replace with the <para></para> tags. is trying to be used as line break which is the incorrect usage.
<summary> - Brief overview about the current identifier. This is typically what the user sees with Intellisense inside of Visual Studio. So be short, concise, helpful.
<remarks> - This is full description about the current class or class member in full detail.
<ul>,<ol>,<li> - These do work in SandCastle with the SHFB. Microsoft wants you to use the <list> & <item> tags, however the html versions are easier to type and read.

XML Doc Comments References

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.,
Unknown macro: {@link IndexWriter}
) use this method to advance the stream to
the next token. Implementing classes must implement this method and update
the appropriate
Unknown macro: {@link AttributeImpl}
s with the attributes of the next
- token.
- 
- 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
- Unknown macro: {@link #captureState}
 to create a copy of the current attribute state.
- 
- This method is called for every token of a document, so an efficient
- implementation is crucial for good performance. To avoid calls to
- Unknown macro: {@link #addAttribute(Class)}
 and
 Unknown macro: {@link #getAttribute(Class)}
 or downcasts,
- references to all
s that this stream uses should be
retrieved during instantiation.
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
Unknown macro: {@link #incrementToken()}
.
*
@return false for end of stream; true otherwise
*
Note that this method will be defined abstract in Lucene

3.0.
*/


h4. Xml Doc Comments - ImplementToken()

{code:xml}
        /// <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>

Child pages

Documenting Lucene.Net

Documentation Goals

XML Doc Comments Guide

XML Doc Comments References

Example of Converting JavaDoc into XML Doc Comments

Java Docs - implementToken()