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 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 or even can have examples, and that's fine.
• 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 hidden="false">
    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" />
    <hostapp name="EXCEL.EXE" />
    <example hasresult="true">
    <module name="Class1" type="Class Module">
    <![CDATA[
    Public Sub CodeExample()
        'code example 
    End Sub
    ]]>
    </module>
    <module name="Module1" type="Standard Module">
    <![CDATA[
    Public Sub DoSomething()
        'code example 
    End Sub
    ]]>
    </module>
    </example>
    <example hasresult="false">
    <![CDATA[
    Public Sub CodeExample()
        'code example 
    End Sub
    ]]>
    </example>

The <summary> tag can have a hidden attribute; if the value is "true", the inspection will not appear on the website. This attribute should be reserved for Easter Egg inspections.

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. Hence, there should be a <reference> tag for each RequiredLibraryAttribute decorating an inspection type.

If an inspection has a [RequiredHost("HOST.EXE")] attribute, it should have a <hostapp name="HOST.EXE" /> tag.

<example> tags must have a hasResult attribute with a value of "true" or "false", and may contain either:

• one or more <module> tags that contain <![CDATA[{code block}]]> tag that begins and ends on a new line;
• nothing other than a <![CDATA[{code block}]]> tag that begins and ends on a new line:

<example hasResult="true">
<![CDATA[
Public Sub DoSomething()
End Sub
]]>
</example>

If a <module> tag is used for one example, use it in all examples for that inspection. You may use a name attribute to label the module block. If the module type is relevant, specify a type attribute value.

Only one <![CDATA[{code block}]]> block may appear under any given <example> tag, unless it's wrapped in a <module> tag.

<remarks> tags are also picked up when present.