| Wiki Markup |
|---|
h2. 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. h2. 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 <p></p> -* Denotes a paragraph. The XML doc comments for whatever reason uses the longer form tag of <para>. If you see *<p />,* replace with the <para></para> tags. <p /> 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. h2. XML Doc Comments References * [Recommended Tags For Documentation Comments|http://msdn.microsoft.com/en-us/library/5ast78ax.aspx] * [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 - 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> {code} |
Page History
Overview
Content Tools
Apps