Inspections xml doc

Website Integration

Since v2.4.1.4719, build assets include Rubberduck.CodeAnalysis.xml, a file generated on build, containing all the XML comments in Rubberduck.CodeAnalysis.

The project's website is now downloading this xml file to extract the documentation for all types whose name ends with Inspection. When invalidating its 24-hour cache, the website attempts to pull the xml asset from the latest "green-release" off the [master] branch, and the same xml asset from the latest "pre-release" tag off the [next] branch; inspections that exist in [next] but not in [master] will be marked in the inspections/list page with a "PreRelease" label (unless no xml asset is found in [master], as is currently the case as of this writing).

In order for this to work, xml documentation for inspection classes must follow a number of rather strict rules:

• Rubberduck's parser must be able to parse the VBA code examples; keep in mind that precompiler directives (e.g. #If, #Const, etc.) are handled in a separate parser - the website does not "pre-process" the code samples, so precompiler directives are not allowed.
• Not all inspections need examples, but when they do, the first example must be an example of code that triggers the inspection.
• If more examples are provided, they must be examples of code that do NOT trigger the inspection.
• Website does not honor any html formatting present in the xml documentation.

The structure of an inspection's xml-doc comment must be as follows:

    <summary>
    short, single-sentence description of the inspection that comfortably reads in IntelliSense.
    </summary>
    <why>
    a paragraph that describes the reasoning of the inspection in details.
    </why>
    <reference name="RequiredLibrary" />
    <example>
    <![CDATA[
    Public Sub CodeExample()
        'code example 
    End Sub
    ]]>
    </example>
    <example>
    <![CDATA[
    Public Sub CodeExample()
        'code example 
    End Sub
    ]]>
    </example>

The <reference> tag is needed when the inspection has a [RequiredLibrary("LibraryName")] attribute; the website uses this information to indicate that the inspection will only run when the specified library is referenced.