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.
Related
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
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
I've created a SpecFlow Plugin following their page below. And have created a Generator Plugin as I needed to modify the auto generated code behind my features.
https://github.com/techtalk/SpecFlow/wiki/Plugins.
SpecFlowPlugin Code
[assembly: GeneratorPlugin(typeof(SpecFlowSpiraAdapterPlugin))]
namespace SpiraTest.SpecFlowPlugin
{
/// <summary>
/// A adapterpPlugin is needed to use a custom MSTest generator with SpecFlow.
/// </summary>
public class SpecFlowSpiraAdapterPlugin : IGeneratorPlugin
{
/// <summary>
/// By implementing the Initialize- Method on the IGeneratorPlugin interface, you get access to the GeneratorPluginEvents and GeneratorPluginParameters
/// </summary>
/// <param name="generatorPluginEvents"></param>
/// <param name="generatorPluginParameters"></param>
public void Initialize(GeneratorPluginEvents generatorPluginEvents, GeneratorPluginParameters generatorPluginParameters)
{
generatorPluginEvents.CustomizeDependencies += GeneratorPluginEvents_CustomizeDependencies;
}
private void GeneratorPluginEvents_CustomizeDependencies(object sender, CustomizeDependenciesEventArgs e)
{
e.ObjectContainer.RegisterTypeAs<MSTestCustomGenerator, IUnitTestGeneratorProvider>();
}
}
}
Problem
I'm getting an error message when trying to run my tests indicating that i don't have the below attribute.
[assembly:RuntimePlugin] attribute
However I don't need that attribute as I have the [assembly: GeneratorPlugin] attribute instead.
No idea why it's saying that. Any ideas?
Message: Class Initialization method
MiJobsAdminPortal.UITests.Login.LoginFeature.FeatureSetup threw
exception. TechTalk.SpecFlow.SpecFlowException:
TechTalk.SpecFlow.SpecFlowException: Missing [assembly:RuntimePlugin]
attribute in SpiraTest.SpecFlowPlugin, Version=1.0.0.0,
Culture=neutral, PublicKeyToken=null. Please check
http://go.specflow.org/doc-plugins for details..
For SpecFlow every plugin is a Generator and a Runtime plugin, except you configure it otherwise. This is the code for that: https://github.com/techtalk/SpecFlow/blob/master/TechTalk.SpecFlow/Infrastructure/ContainerBuilder.cs#L127
As an example for configuration, have a look at the configuration of the SpecFlow+Excel plugin, which is also only a generator plugin.
<specFlow>
<plugins>
<add name="SpecFlow.Plus.Excel" type="Generator" />
</plugins>
</specFlow>
You have to specify the type as Generator. If not SpecFlow is always searching for both plugin types.
This behaviour is not documented, but is there since years. I will update the documentation in the next days.
Full disclosure: I am one of the maintainers of SpecFlow & SpecFlow+
On the base of the XML-comments I generate the documentation by Sandcastle. I want to generate the English and Russian version of the documentation.
My XML-files Magic.doc.enu.xml and Magic.doc.rus.xml are located in the same project (the target dll).
For example I can do it through such ugly way:
namespace HelloDocs {
#if ENU
/// <include file='Magic.doc.enu.xml'
/// path='Documentation/Member[#Name="HelloDocs.Magic"]/*'/>
#elif RUS
/// <include file='Magic.doc.rus.xml'
/// path='Documentation/Member[#Name="HelloDocs.Magic"]/*'/>
#endif
public class Magic {
#if ENU
/// <include file='Magic.doc.enu.xml'
/// path='Documentation/Member[#Name="HelloDocs.Magic.Foo()"]/*'/>
#elif RUS
/// <include file='Magic.doc.rus.xml'
/// path='Documentation/Member[#Name="HelloDocs.Magic.Foo()"]/*'/>
#endif
public void Foo() { }
}
}
Can I do the switching of the XML-files without the ugly #if\#elif\#endif syntax?
I solved this problem. I published its detailed description here.
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; }