Page History

  /**
    Guide

* *<c> vs <code> -*&nbsp;<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.&nbsp;
* \*<see cref="">&nbsp;vs&nbsp;\{@link indentifer }\* \-&nbsp;use the <see> tag in place of the&nbsp;\{@link &nbsp;Identifier}. &nbsp;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&nbsp;parentheses, you will also need to include the types of each argument.&nbsp;\{@link #getAttribute(Class)} in JavaDoc would be turned into <see cref="AttributeSource.GetAttribute(System.Type)" /> &nbsp;
* *<exception cref="" /> vs @throws* \-\- lists the possible exception. &nbsp;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>&nbsp;
* *Obsolete vs @deprecated* \- Is notated by the Obsolete Attribute. JavaDoc uses @deprecated. There is not an XML&nbsp;equivalent, however SandCastle will make note of this for you, if your uses the Attribute.&nbsp;
* *<returns></returns> vs @return* \- Describe what the return object is.
* *<para></para> vs <p></p> -* Denotes a paragraph. &nbsp;The XML doc comments for whatever reason uses the longer form tag of <para>. &nbsp;If you see *<p />,* replace with the <para></para> tags. &nbsp;<p /> is trying to be used as line break which is the incorrect usage. &nbsp;
* *<summary>*&nbsp;\- Brief overview about the current&nbsp;identifier. This is typically what the user sees with Intellisense inside of Visual Studio. So be short, concise, helpful. &nbsp;
* *<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.


h2. XML Doc Comments References

* [Recommended Tags For Documentation Comments|http://msdn.microsoft.com/en-us/library/5ast78ax.aspx]&nbsp;
* [Sandcastle on Codeplex|http://sandcastle.codeplex.com/]
* [http://shfb.codeplex.com/][Sandcastle Help File Builder|http://shfb.codeplex.com/]
* [GhostDoc|http://submain.com/products/ghostdoc.aspx]


h2. 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.

h4. Java Docs - implementToken()

{code}

{code}
/*\*
* 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>
\   */
{code}

h4. Xml Doc Comments - 

{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>
{code}