You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

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 Eqivalents

TODO

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., {@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>
  • No labels