0

I have a Visual Studio C# project with XML documentation comments. I get a .xml file with <summary>, <param>, <returns> and <example> members.

The text I put inbetween the <summary> tags is shown in the help file as well as Namespace, Assembly, Example and See Also sections. Just <param> and <returns> don't even have an empty section even though it builds with no errors.

Relevant part of the generated .xml:

<member name="M:OPC_ClientLib.OPC_Client.getBit(System.String)">
    <summary> the summary text (is shown) </summary>
    <param name="variable">Variable name (not shown)</param>
    <returns>true or false, (not shown)</returns>
    <example>
        <code> bool bit = getBit("bitname")</code>
    </example>
</member>

Actual output

enter image description here


I use Sandcastle Help File Builder GUI Version 2018.5.29.0.

I tried to show anything in the project properties which gave me a lot of unwanted extra elements in the documentation but none of which got me <return> or <params>.

Thomas Flinkow
  • 4,845
  • 5
  • 29
  • 65
Simon
  • 115
  • 2
  • 6

3 Answers3

0

Can you tick

Include a 'missing documentation' warning for XML comment elements not present

for both <param> and <return> tags? Does it change anything? You should at least get the Parameters and Return Value sections in your documentation.

enter image description here


If that does not work either, make sure you have ticked

XML documentation file

in Visual Studio on the project properties Build page as described here.

enter image description here

Thomas Flinkow
  • 4,845
  • 5
  • 29
  • 65
  • i have checked the "XLM documentation file:" and the file is generated, if I look in the file it looks okay and the return and param tags are there. I also have checked the missing documentation warning. For a missing summary that works, but for returns or params i dont even get the red warning if i remove the text – Simon Jun 06 '18 at 11:15
  • @Simon can you show the relevant parts of the `.xml` file and of the generated help file? – Thomas Flinkow Jun 06 '18 at 11:16
  • the summary text (is shown) Variable name (not shown) true or false, (not shown) bool bit = getBit("bitname") – Simon Jun 06 '18 at 11:19
0

For some reason if I make a Sandcastle Project in Visual Studio the Problem is resolved and i also get a Syntax section which is quite nice. I still don't understand why this isn't working in the Sandcastle GUI but this works for me. Thanks for your help

Edit: actually I just found the real Problem. When I included the Project I thought I had to change the target Framework from 4.5 to 4.6.1 like it is in my C# Project. Changing it back oddly does not resolve the issue but making a new Project without changing that property does. Just in case someone has the same issue.

Simon
  • 115
  • 2
  • 6
0

I had this issue, and I finally figured it out. The problem was that in my Documentation Sources, I was only referencing the DLL file, so basically, Sandcastle was using Reflection to generate the Help files, which is only the bare minimum information, and does not include the XML comments.

The solution is to set your project Build settings to generate an XML help file, and then add that XML file to the Documentation Sources in the right side panel of the Sandcastle UI app.

Once I did that, all my XML comments were included in the Help.

Here is a screenshot of my Sandcastle UI setup. Notice the right hand panel.