Documenting Lucene.Net

Transcription

1 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 TODO JavaDoc & XML Doc Comments Equivalents Supported? means is it supported by sandcastle or SHFB Java Doc Tag XML Doc Comments Element Required Supported?* <author>[value]</author> No No The author tag tends to help who is responsible for a class or <version>[value]</version> No No The version tag defines the version of the <param name=""></para> Yes Yes Describes a parameter in a method signature. This is often auto-generated by Visual Studio for methods. <typeparam name=""> </typeparam> Yes Yes Describes a generic type <returns></returns> Yes Yes Only for methods that have a return value. This is a good place to note if the method can return null <exception cref="[type]"> </exception> <exception cref=""> </exception> No Yes This denotes when a class method or property can throw an exception and the exception type that it throws. The description will tell the case of why an exception is thrown if its not obvious. No Yes Same as above <value></value> Yes Yes Describes what the property [value] represents. <permission cref="[member]" /> No Yes Notes the access level of a type or <seealso cref="[member]" /> No Yes This links documentation that would beneficial in viewing in the relation to the current documentation. This is placed in the "See Also" section at the bottom of the page.

2 ref} <see cref="[member]" /> Yes Yes This will create a link for the specified member. The cref part of this can become tricky, especially with overloaded methods and generics. In JavaDoc the sharp (#) prefix denotes a member, i.e. {@link #methodname(class, TokenStream)} In.Net, this would be <see cref="classname. MethodName(Type, TokenStream)" /> {@link ref} <paramref name="[member]" /> Yes Yes Inline element that references a parameter of the method, typically used inside of the remarks or summary section. {@link ref} <typeparamref name="[member]" /> Yes Yes Inline element that references a generic type parameter of the method, typically used inside of the remarks or summary <since>[value]</since> No No This describes that this functionality was supported starting in version No Unsure [Serializable] - Sandcastle could use the [Serializable] attribute to denote this in the generated documentation, but this needs to be No Yes [Obsolete] - Sandcastle / SHFB does make use of the [Obsolete] attribute to note that method is deprecated in the generated docs. <summary><summary> Yes Yes Give a brief overview about a class, namespace or member does in the code. Intellisense will pick up summary and use it inside of Visual Studio. Be concise. <remarks>[xml]</remarks> Yes Yes Give the full explanation of what class, namespace or member does in the code. This typically should include code examples. <example>[xml]</example> No Yes Denotes a full section targeted towards providing an example in the generated docs. [<p />] <para>[text]</para> Yes Yes This should always be used for paragraphs inside of the <remarks /> section. In Javadocs <p> is often used as line break and it does not wrap the paragraph. In the xml, it needs to wrap the paragraph text. <code /> <c>[type value]</c> Yes Yes Instructs Sandcastle to format the text as code. examples: <c>null</c>, <c>true</c>, <c>tokenstream< /c>, <c>string</c> JavaDocs will often wrap this inside of <code /> tags. This will cause formatting issues if its carried over to the.net comments. Sandcastle will attempt to render as a code example. <code /> <code lang="[lang]"> [example] </code> No Yes This element specifies a code example. SHFP supports the lang attribute, so it would be wise to denote which language the code example is in.

3 <ul>,<ol> <list> Yes Yes When creating a list, you should use the <list> element. However SHFB will let <ul> and <ol> elements be used in the generated docs. <li> <item> Yes Yes When creating a list item, you should use the <item> element. SHFP will let <li> be used in the generated docs. <include file="[filepath]" path="tagpath[@name=id]" /> No Yes This element will let you include documentation from another file and tag. The "path" attribute is the xpath query to the member you wish to link. This an alternative to putting the documentation inside the code. It can also be more complicated. <note>[xml text]</note> No Yes Nonstandard. This tag is supported by SHFB and possibly even Sandcastle. This was an NDoc tag that was requested heavily. This creates a note block inside the generated docs. <inheritdoc /> No Yes Nonstandard. This tag is supported by SHFB. This will specify SHFB to use documentation from the inherited member documentation. XML Doc Comments References Recommended Tags For Documentation Comments Sandcastle on Codeplex 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()

4 /** * 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. * 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. * 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()}. * false for end of stream; true otherwise * * <b>note that this method will be defined abstract in Lucene * 3.0.</b> */ Xml Doc Comments - ImplementToken()

5 /// <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> /// 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. /// 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. /// 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()" />. /// <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>