Unexpected error while generating inherited documentation

[lennoncork]

We have an legacy project that uses an old version of sandcastle. Upgrading to the latest version results in an argument null exception. This looks like it's isolated to a couple of projects, as we can build the documentation for most just fine. Tracking down the issue is very difficult with the stack trace.

Would it be possible to add some details about the file/line that is being processed so that it's easier to locate the issue?

Alternatively, is it possible to debug the build process so we can see the stack trace in more detail?

...GenerateInheritedDocs.proj(28,3): error GID0001:  Unexpected error while generating inherited documentation:
...GenerateInheritedDocs.proj(28,3): error GID0001: System.ArgumentNullException: Parameter "message" cannot be null.
...GenerateInheritedDocs.proj(28,3): error GID0001:    at Microsoft.Build.Shared.ErrorUtilities.VerifyThrowArgumentNull(Object parameter, String parameterName, String resourceName)
...GenerateInheritedDocs.proj(28,3): error GID0001:    at Microsoft.Build.Utilities.TaskLoggingHelper.LogWarning(String subcategory, String warningCode, String helpKeyword, String helpLink, String file, Int32 lineNumber, Int32 columnNumber, Int32 endLineNumber, Int32 endColumnNumber, String message, Object[] messageArgs)
...GenerateInheritedDocs.proj(28,3): error GID0001:    at Microsoft.Build.Utilities.TaskLoggingHelper.LogWarning(String message, Object[] messageArgs)
...GenerateInheritedDocs.proj(28,3): error GID0001:    at SandcastleBuilder.Utils.InheritedDocumentation.GenerateInheritedDocs.InheritDocumentation(XmlNode member)
...GenerateInheritedDocs.proj(28,3): error GID0001:    at SandcastleBuilder.Utils.InheritedDocumentation.GenerateInheritedDocs.InheritDocumentation(XmlNode member)
...GenerateInheritedDocs.proj(28,3): error GID0001:    at SandcastleBuilder.Utils.InheritedDocumentation.GenerateInheritedDocs.ScanCommentsFiles()
...GenerateInheritedDocs.proj(28,3): error GID0001:    at SandcastleBuilder.Utils.InheritedDocumentation.GenerateInheritedDocs.Execute()

[EWSoftware]

Normally, the warning would have provided the necessary info. However, it looks like the LogWarning() method overloads changed in MSBuild and it is picking the wrong overload when I pass a StringBuilder for the message rather than explicitly converting it to a string.

Given that you're working with an old project and assuming it built without warnings before, the most likely warning causing the issue is GID0010. A member using inheritdoc is using the deprecated select attribute rather than the path attribute. That was added in November 2019. Other possibilities are "no comments found" warnings but you'd have seen them with the prior version as well. If that's the case, review all uses of inheritdoc and ensure the target member IDs are valid.

Update: It looks like the only warning affected by this issue is actually GID0009, a circular reference warning where a method imports comments from itself or another member that's already been encountered. If it's a case where that's okay and you've been ignoring it, I'll try to have an update out this weekend that fixes it.

[lennoncork]

That's a good lead, I'll take a look over the comments next week and try and find the circular reference. A fix would be very much appreciated, but will report back soon with an update. Thanks for all the great work!

[EWSoftware]

The new release is available that should fix the issue (v2022.1.22.0).