I've run into this before but it was years ago (Sandcastle 4.9 and MSVS 2012). Does anybody have any idea of how to troubleshoot such a diagnostic (that's my explicit question)?
Opening the .docx file in, say, Notepad or Notepad++ is of no use (the file is usually too large for Notepad, and even if Notepad++ can open it, the delay is agonizing). Don't bother with the Sandcastle log, even at verbose level, in this case, it thinks it has done just a grand job! After all, it did produce the .docx file without suffering a cruel death or catching fire.
Steps to Reproduce
- Build with MSVS, producing the documentation XML
- Run Sandcastle against the XML (and DLL or whatever) to make an open XML document (filetype .docx)
- Open that .docx file
- Scream in frustration when you see the diagnostic, or, if you don't, count yourself lucky
In the meantime, as work-arounds, I've found the following C# XML documentation elements seem to trigger this behavior:
Bounded seealso
<seealso cref="item">Don't do this!</seealso>
use only
<seealso cref="item"/>
para
<para>...</para>
this construct often works ... but when it doesn't...
A workaround is to use<br/>
instead of the leading para tag and omit any trailing tag