Odd Warnings for Missing Documentation that is Not Missing

Apr 10, 2009 at 10:43 PM
We are getting several warnings in our output about missing documentation tags that are actually present.  For example, here is a method with it's documentation comment:

 

/// <summary>

 

 

/// Returns a number from 0 to 100 indicating the approximate percentage of completion.

 

 

/// Will return a value of 100 only after the method is completely finished.

 

 

/// If the implementation doesn't support an ongoing progress indication, the

 

 

/// method returns -1.

 

 

/// If the implememtation doesn't support a status indication the status is null

 

 

/// Note the progress and the status aren't linked so neither, either or both might be supported

 

 

/// </summary>

 

 

/// <param name="status">null indicates that there is no status information available</param>

 

 

/// <returns> -1 indicates that there is no progress information available</returns>

 

 

int GetProgress(out string status);

 


Yet the output shows:

Warn: ShowMissingComponent: Missing <summary> documentation for M:Cognex.Cnx.ComponentModel.ICnxAsyncMethod.GetProgress(System.String@)


Warn: ShowMissingComponent: Missing <param name="status"/> documentation for M:Cognex.Cnx.ComponentModel.ICnxAsyncMethod.GetProgress(System.String@)

Warn: ShowMissingComponent: Missing <returns> documentation for M:Cognex.Cnx.ComponentModel.ICnxAsyncMethod.GetProgress(System.String@)

Obviously this method has the summary, parameters and returns tags.  This is frustrating as we use these warnings to catch methods that are actually missing documentation.  I am using SHFB v1.7.  BTW, we have created a utility that copies our SHFB project and reverses the isExposed attribute for each filter element in the apiFilter element.  This is done so we can include a "none" type reference to this project to avoid the unresolved warnings.  I also do not copy the plugIn element whose id is "Additional Reference Links".  Earlier when I was not doing that it cause a circular reference and failed to load.  I mention this as it is a little odd, but I do not think it has anything to do with the issue at hand.

Pat O
Coordinator
Apr 11, 2009 at 3:28 AM
Do you have the problem if you just create a project in SHFB rather than a modified version created by your utility?  If you can send me a small example project that demonstrates the problem, I'll look into it.  My e-mail address is in the About box and in the footer of the pages in the help file.

Eric