I am having trouble with an xml comment on a web api controller method. I have a class with several properties as a parameter on this method. When I want to add a description to the properties within that class on the method it builds it with an extra extension, and swagger cannot interpret the documentation for its UI. This worked just fine in visual studio 2013 but in 2015 it changes the output to the xml documentation file.
My methods xml Comments:
/// <summary>
/// Get alerts for your Id.
/// </summary>
/// <param name="Id"></param>
/// <param name="alertRequest"></param>
/// <param name="alertRequest.category">Accepted Values: examples of accepted values are...</param>
My Method:
[HttpGet]
public IHttpActionResult GetOpenAlerts(Guid Id, [FromUri] AlertRequest alertRequest){}
XML output when compiling in Visual Studio 2013:
name="Api.Controllers.AlertController.GetOpenAlerts(System.Guid,Api.Domain.Models.AlertRequest)">
<summary>
Get alerts for your Id.
</summary>
<param name="Id"></param>
<param name="alertRequest"></param>
<param name="alertRequest.category">Accepted Values: examples of accepted values are ...</param>
<returns></returns>``
Output in Visual Studio 2015:
<member name="Api.Controllers.AlertController.GetOpenAlerts(System.Guid,Api.Domain.Models.AlertRequest)">
<summary>
Get alerts for your Id.
</summary>
<param name="Id"></param>
***<param name="alertRequest.category.category"***>Accepted Values: examples of accepted values are...</param>
<returns></returns>
Is there a setting I need to change for xml comments in visual studio 2015? Why does it automatically add the extra extension and duplicate the property?
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'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?
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.
I'm having an issue with RazorEngine (version 3.4.1.0).
I'm using Razor.Parse method with very simple template in a service that fires up every few minutes, and it works without any issues most of the times, but every now and then it throws this exception on me:
System.IO.FileNotFoundException:
Could not find file 'C:\Users\username\AppData\Local\Temp\cw3sv4yk.dll'.
File name: 'C:\Users\username\AppData\Local\Temp\cw3sv4yk.dll'
(cw3sv4yk is a randomly generated name)
Has anyone bumped into this issue before, and if so - any hints to what the solution would be?
Thanks,
Przemek
EDIT:
I've just noticed that I'm also getting this exception occasionally:
RazorEngine.Templating.TemplateCompilationException: Unable to compile
template. Metadata file
'c:\Windows\Microsoft.NET\Framework\v4.0.30319\mscorlib.dll'
could not be opened -- 'The process cannot access the file because it
is being used by another process.'\n\nOther compilation errors may
have occurred. Check the Errors property for more information.
EDIT_2:
One more exception that's being thrown every now and then:
System.ArgumentException: Class name is required
Using an overloaded version of Razor.Parse method which caches templates solved the issue for us:
/// <summary>
/// Parses and returns the result of the specified string template.
/// </summary>
/// <typeparam name="T">The model type.</typeparam>
/// <param name="razorTemplate">The string template.</param>
/// <param name="model">The model instance.</param>
/// <param name="cacheName">The name of the template type in the cache or NULL if no caching is desired.</param>
/// <returns>The string result of the template.</returns>
public static string Parse<T>(string razorTemplate, T model, string cacheName)
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; }