XML Documentation validation

Feb 14, 2008 at 6:39 AM
Hi,

I am using SandCastle to build CHM files for my project. I have enabled the XML Documentation file checkbox under the Outout section of my project to generate the XML file. My problem is that I want to check to see if the parameters in the XML comments in the methods in the classes match with that of the actual parameters implemented in the methods. Let's consider the following example:

/// <summary>
/// This method will filter the item datatable to the current selected store and call the SetItemField method to update the item specific fields
/// </summary>
/// <param name="outputSection"></param>
/// <param name="intermediateSection"></param>
/// <param name="intermediateSectionDMI"></param>
/// <param name="currentStoreNumber">Current selected store number</param>
public override void SetItemFieldValues(ISectionOutput outputSection, SectionComponent m_intermediateSection, String currentStoreNumber)
{
// some code here
}

In the above code snippet, the number of parameters in the comments is not equal to the actual number of parameters in the method. So, how can I use SandCastle to validate this?

Anybody has a solution, please let me know.

Thanks,
Adarsh
Feb 26, 2008 at 12:15 AM
Edited Feb 26, 2008 at 12:20 AM
Hi Adarsh,

This forum is for discussions about CodePlex only.

In the future, use the Sandcastle discussions area instead: http://www.codeplex.com/Sandcastle/Thread/List.aspx.

You request is already built-in to the C# compiler though. After building documentation check the list of warnings and you should the following:

  1. XML comment on Namespace.Type.SetItemFieldValues(...)' has a param tag for 'intermediateSection', but there is no parameter by that name
  2. XML comment on Namespace.Type.SetItemFieldValues(...)' has a param tag for 'intermediateSectionDMI', but there is no parameter by that name
  3. Parameter 'm_intermediateSection' has no matching param tag in the XML comment for 'Namespace.Type..SetItemFieldValues(...)' (but other parameters do)
(1, 2) Compiler Warning (level 2) CS1572
http://msdn2.microsoft.com/en-us/library/hba91y19.aspx

(3) Compiler Warning (level 4) CS1573
http://msdn2.microsoft.com/en-us/library/01248w2b.aspx

- Dave

(EDIT: Added warning #3)