Why are my code blocks not rendering in the Sandcastle Help File? - c#

I'm using the current version of Sandcastle from Codeplex that is integrated with VS.NET 2012 to build a .cmh help file. The help file is being created, but I can't seem to ever get any of my <code> blocks to emit in the help file. I have the following easy example I keep working with:
/// <summary>
/// This is the summary
/// </summary>
/// <code>var s;</code>
public string SomeValue { get; set; }
When I look at the output .chm file, the var s; code is not present anywhere. I have done the following:
Added reference to Code Block Component in the Sandcastle project properties.
Tried making tag <code lang="C#">var s;</code> and <code language="C#">var s;</code> but neither made a difference.
Read documentation on the following sites detailing this process but to no avail:
https://www.simple-talk.com/dotnet/.net-tools/taming-sandcastle-a-.net-programmers-guide-to-documenting-your-code/
http://www.ewoodruff.us/shfbdocs/
The example is obviously a simplified version, but I'm just trying to get the basics work here. What am I doing incorrectly or missing?


I don't think the code tag is allowed to be by itself, try putting it inside an <example> tag, like <example><code>var s;</code></example>. So this should work:
/// <summary>
/// This is the summary
/// </summary>
/// <example>
/// <code>var s;</code>
/// </example>
public string SomeValue { get; set; }

Related

Why can't I see my <example>s and <code>s from Intellisense? using C# and Visual Studio 2017-2019

I am currently using Visual Studio 2019 to write a WPF/C# application.
After writing a new method I decided to add some examples for better usage.
But my example won't show up in the Intellisense popup.
I've tried the following code:
/// <summary>...</summary>
/// <param name="path">...</param>
/// <param name="action">...</param>
/// <example>
/// Use this method like this:
/// <code>
/// MyMethod("C:\\someFile.txt", s => File.Copy(s, "C:\\someFile (copy).txt"));
/// </code>
/// </example>
public static void MyMethod(string path, Action<string> action)
{
// some code ...
}
I expected my example to show up on the Intellisense popup that pops up when calling from another file.
What happens is just the summary shows up without my examples..

It is simple - because it works so. And never worked as you expected.
Your XML comments is fine but Visual Studio shows only <summary> section (Short discription of class \ method or property) for quick familiarize with class \ method or property you are going to use.
XML comments can be very big, litterally nothing limits it size. Imagine what size shoud be tooltip to show you big comments?
So if you or other developer use Visual Studio and tooltip with <summary> does not give you enough information - just simply go to decloration with F12 and read full comment OR you can show declaration right in current section with ALT + F12
Not shure but i think it can be some extensions for showing tooltip as you want

How to Fast View binary/.txt resources?

I've got .ps1 scripts in my solution which added as .txt files into resources.
I use them in code this way:
string script = Properties.Resources.TRY_GET_GUEST_SCRIPT_SESSION_RESULT;
The problem is that I have no instruments to fast view content of this resource - the autogenerated function TRY_GET_GUEST_SCRIPT_SESSION_RESULT has only a brief annotation, in addition, has an uncomfortable 'comment' format:
/// <summary>
/// Looks up a localized string similar to Param(
/// [parameter(Mandatory=$true)]
/// [guid]
/// $SessionId
...[rest of string was truncated]"
/// </summary>
Which plugins, or code-tricks I can use to fast view (by press F12 - for ex.) resource?

How to Import documentation from .xml file to .cs file programmatically?

I heve documentation in .xml file that looked like this:
<?xml version="1.0"?>
<doc>
<assembly>
<name>ClassLibrary2</name>
</assembly>
<members>
<member name="T:ClassLibrary2.Class1">
<summary>
Class1 Dummy documentation
</summary>
</member>
<member name="M:ClassLibrary2.Class1.Func1">
<summary>
Func1 Dummy documentation
</summary>
</member>
</members>
</doc>
And I wont to import the documentation to .cs file that looked like this:
namespace ClassLibrary2
{
public class Class1
{
void Func1()
{
}
}
}
So that after my import my file will look like this:
namespace ClassLibrary2
{
/// <summary>
/// Class1 Dummy documentation
/// </summary>
public class Class1
{
/// <summary>
/// Func1 Dummy documentation
/// </summary>
void Func1()
{
}
}
}
How can I do this programmatically?
Should I use CodeDOM Or Visual Studio? Or Roslyn Or another tool?
Any help would be appreciated,
Thanks in advance.

use CodeDom, Roslyn is the compiler platform and will not help you for your problem.
Load the cs into a codedom graph
Find the methods / properties in the graph and add a CodeCommentStatement - see https://learn.microsoft.com/en-us/dotnet/framework/reflection-and-codedom/how-to-create-an-xml-documentation-file-using-codedom
Generate a new source file from the graph (example is in the link I've provided )
EDIT:
maybe it's easier to use the Microsoft.CodeAnalysis (add the Microsoft.CodeAnalysis.CSharp nuget package) library of roslyn
var syntaxTree= CSharpSyntaxTree.ParseText(code);
//search for the methods and properties and add comments
// ** your code **
//
//getting the new sourcecode
var root = (CompilationUnitSyntax)syntaxTree.GetRoot();
var mc= new ModelCollector();
mc.Visit(root);
string newCode = JsonConvert.SerializeObject(mc.models);
Here is the Method for creating new comments:
https://learn.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.csharp.syntaxfactory.comment?view=roslyn-dotnet
complete doc of the lib:
https://learn.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.csharp?view=roslyn-dotnet

How to configure summary comment on method in Visual Studio

When typing "///" above the method in Visual Studio, it generates XML summary.
For example:
/// <summary>
///
/// </summary>
/// <param name="par1"></param>
/// <param name="par2"></param>
/// <returns></returns>
public string Foo(int par1, string par2)
{
return "";
}
Is there a setting somewhere where I can stop adding the following line?
/// <returns></returns>

After some more research and several comments, I don't believe there is such setting or feature to customize the auto addition of
//<returns></returns>
This applies to VS2017 and earlier. Maybe this will be come a feature sometime in the future.

XML-documentation for a namespace

Would you write xml-doc for a namespace? And if yes, how and where?
I would think, if it is possible, maybe an almost empty file like this:
/// <summary>
/// This namespace contains stuff
/// </summary>
namespace Some.Namespace
{
}
But will that work? Since you... "declare", or at least use the namespace in all the other files as well... and what would happen if you wrote an xml-documentation thing somewhere else on the same namespace? Would one be gone? Or would they be merged somehow?

NDoc supports this by recognising a special NamespaceDoc class located in each namespace, and using the documentation from that. I haven't tried it, but Sandcastle appears to support the same trick.
Edit:
For example:
namespace Some.Namespace
{
/// <summary>
/// This namespace contains stuff
/// </summary>
public static class NamespaceDoc
{
}
}

Sandcastle does not support the NamespaceDoc directly, but if you use Sandcastle Help File Builder you can use the NamespaceDoc class mentioned by Tim.
namespace Example
{
/// <summary>
/// <para>
/// Summary
/// </para>
/// </summary>
/// <include file='_Namespace.xml' path='Documentation/*' />
internal class NamespaceDoc
{
}
}
SCHB also extends the syntax slightly and allows embedding code examples straight from code files. An example _Namespace.xml:
<?xml version="1.0" encoding="utf-8" ?>
<Documentation>
<summary>
<h1 class="heading">Example Namespace</h1>
<para>
This namespace is used in the following way:
</para>
<code source="Examples\Class.cs" lang="cs"></code>
<code source="Examples\Class.vb" lang="vbnet"></code>
<para>
Hopefully this helps!
</para>
</summary>
</Documentation>
Including documentation in XML file allows you to write short summary in code and larger description in a separate XML file for the help file. This way the code isn't cluttered with all the details and remains easily readable.

Sandcastle Help File Builder supports comments on namespaces. Open your Sandcastle project. In Project Properties window navigate to Summaries and click on the Edit Namespace Summaries button.

You can do it in doxygen using:
/// <summary>
/// description
/// </summary>
namespace name{};
Also, it's a good practice to declare your namespaces in a NameSpaces.cs file, and comment them only in this file.

If you use Sandcastle and its "Help File Builder" you can document namespaces and Namespace-Groups using the following Code in your Projects:
namespace Company.Product.Widgets
{
/// <summary>
/// These are the namespace comments for <c>Company.Product.Widgets</c>.
/// </summary>
[System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
class NamespaceDoc
{
}
}
If the project has namespace grouping enabled, you can also maintain the namespace group comments using a NamespaceGroupDoc class in a similar fashion. The following is an example:
namespace Company.Product
{
/// <summary>
/// These are the group comments for namespaces in <c>Company.Product</c>.
/// </summary>
[System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
class NamespaceGroupDoc
{
}
}
To keep the NamespaceDoc class from appearing in the help file, leave off the public keyword and mark it with a CompilerGenerated attribute.
For Reference see here: https://ewsoftware.github.io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm

It is not possible to put comments on namespaces.
UseNamespaceDocSummaries on http://ndoc.sourceforge.net/content/documenters.htm

If using Mono's mdoc documentation system, you can document namespace members by editing the ns-*.xml documentation files.
See the mdoc file format documentation for more details.

Categories

Resources