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
Related
I developing a C# class library in Visual Studio, and I have been making use of XML Documentation Comments primarily for their integration with Intellisense. However, the bulk of comments has become quite cluttered, so now I am endeavoring to use the <include> tag, and an external XML document to reduce the clutter.
My issue is that when using the <include> tag Intellisense seems to not update with the information, not show any of the <summary> and <param> tags that I've assigned to some of my classes and methods.
For Example I could have a class 'Test' documented as shown:
/// <include file="docs.xml" path='extradoc/class[#name="Test"]/*' />
class Test { string foo = "bar"; }
And have docs.xml:
<?xml version="1.0" encoding="utf-8" ?>
<extradoc>
<class name="Test">
<summary>
Contains some Foo.
</summary>
</class>
</extradoc>
And upon build the output XML populates correctly:
<?xml version="1.0"?>
<doc>
<assembly>
<name>Example Program</name>
</assembly>
<members>
<member name="T:Example_Program.Program.Test">
<summary>
Contains some Foo.
</summary>
</member>
</members>
</doc>
The only issue is that, try as I might, this documentation will not appear in the intellisense boxes while appending my code. Is there some Visual Studio configuration setting I'm missing? I've scoured the msn documentation to no avail.
My issue is that when using the tag Intellisense seems to
not update with the information, not show any of the and
tags that I've assigned to some of my classes and methods.
1.Avoid that your issue is being not able to see summary in Intellisense in current project A.
You can get help from this document, this technology is used to provide better reading experience. So assuming you have the Test class in current priject A, when you see the content in VS code editor, you'll see something like:
It's expected behavior that you won't see that rich comments in project A any more cause they have been moved to docs.xml.
2.If you mean when you create a new Project B(or share the assembly to other developers), the Intellisense can't recognize your Test class.
Two possible causes:
1.The output xx.dll and xx.xml from project A are not in the same folder, so when you reference that xx.dll in your new project, Intellisense won't display the documentation comments.
2.I guess there's something wrong with your docs.xml file. (I can't find any official document which indicates this technology supports user-defined nodes like extradoc and class in docs.xml, I used these two nodes and the Intellisense did not work, after changing them to normal docs and members, it works now)
Try using docs.xml and include in this way:
<?xml version="1.0" encoding="utf-8" ?>
<docs>
<members name="MyTests">
<Test>
<summary>
This class is public, but do nothing
</summary>
<remarks>
Just write something here to indicate this is remarks.
</remarks>
</Test>
</members>
</docs>
and
/// <include file="docs.xml" path='docs/members[#name="MyTests"]/Test/*' />
public class Test { }
I suggest you use a public class to test... After that create a new project and reference that xx.dll, when calling Test class you can see the summary:
And if we F12 we can see detailed comments:
Hope it helps :)
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; }
A question of a beginner in c#
from net
using System;
namespace mcMath
{
/// <summary>
/// Summary description for Class1.
/// </summary>
public class Class1
{
public Class1()
{
//
// TODO: Add constructor logic here
//
}
}
}
When I make project, I am getting
using System;
namespace mcmath
{
public class Class1
{
}
}
How can add by default comments, and default constructor. I mean
/// <summary>
/// Summary description for Class1.
/// </summary>
public Class1()
{
//
// TODO: Add constructor logic here
//
}
What I have to do. I am using VS 2008. Regards,
Under the folder C:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE\ProjectTemplates\CSharp\Windows\1033 are all the templates for C# windows projects. You'd have to unzip those, add the comments there, then re-zip them.
Then when you create a new project, the comments will be there.
Likewise, individual items can be found at C:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE\ItemTemplates\CSharp\.
If you don't want to change those versions, you can copy them to C:\Users\<UserName>\Documents\Visual Studio 2010\Templates. Just be sure to update the vstemplate file with new names and GUIDs.
Just click above the class decleration, and start typing 3 slashes: ///
They Visual studio IntelliSense will create the documentation template for you.
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.