I just started using GhostDoc, so I hope mine is not a stupid question. I want to document Class1 by referring to its method Method1. So, I use cref in the description of Class1 as follows.
/// <summary>
/// Use this class to do a lot of things.
/// </summary>
/// <remarks>
/// The most interesting method is <see cref="Method1"/>
/// </remarks>
public class Class1
{
public void Method1(int a)
{ }
}
After building the help file with GhostDoc Pro, I noticed that cref did not "bind", that is, in the documentation under Remarks it says:
"The most interesting method is [Method1]" (with no link to Method1). How can I make the link appear?
You need to use fully qualified method name, for example
<see cref="M:MyNamespace.Class1.Method1(System.Int32)"/>
where MyNamespace is your namespace.
In general it is pretty easy to find correct syntax - turn on XML documentation for project, compile the project, look at the generated XML Comments file for syntax.
For methods that would be
M:<namespace>.<class>.<method name>(<parameters>):<return type>
We don't mind answering GhostDoc questions on SO but you generally you would be get faster help when ask your questions at our community forums - http://community.submain.com
Thanks!
Related
I am working on a Xamarin Form App and we use .resx files for the localizations.
I have got a problem where to my Resources folder I would like to add an audio file called Beep.wav.
Previously in the AppResources.Designer.cs I used to have something like this:
/// <summary>
/// Looks up a localized resource of type System.IO.UnmanagedMemoryStream similar to System.IO.MemoryStream.
/// </summary>
internal static System.IO.UnmanagedMemoryStream Beep
{
get
{
return ResourceManager.GetStream("Beep", resourceCulture);
}
}
but for some reason is not there anymore and when I regenerate that file by adding/removing a string in AppResources.resx file, still it is not there. It does work if I add that manually but everytime we add a new string it gets wiped away.
I am adding some screenshots to give a bit better meaning to what I am trying to achieve:
My resources folder:
My .csproj file for that project
My AppResources.Designer.cs file which should include the piece of code I have typed earlier
How do I get my Beep.wav file included in there?
This is where it is failing as it cannot find "Beep"
private static readonly ISimpleAudioPlayer _beepPlayer;
static MediaPlayerHelper()
{
_beepPlayer = CrossSimpleAudioPlayer.CreateSimpleAudioPlayer();
_beepPlayer.Load(Resources.AppResources.Beep); <--Error
}
Thanks
After creating the .resx file, change Strings to Audio.
Click Add Resource to add the .wav file.
After that, it would generate the code below in AppResources.Designer.cs.
/// <summary>
/// Looks up a localized resource of type System.IO.UnmanagedMemoryStream similar to System.IO.MemoryStream.
/// </summary>
internal static System.IO.UnmanagedMemoryStream WAV_1MG {
get {
return ResourceManager.GetStream("WAV_1MG", resourceCulture);
}
}
I have swagger setup so that it generates the open Api Specification & Swagger Ui on project startup using NSwag based on the controllers in my WebApi.
I would like to enhance the swagger Ui to include
A summary/description for each endpoint
Example parameter inputs for endpoints that require them
Example request body for POST calls
An example access token that can be used only in the swagger documentation to easily authenticate and be able to try everything out (a bit like in this example https://petstore.swagger.io/)
I'm new to NSwag and unsure how to approach adding these enhancements to my code, like where to add them, what i need to use (annotations on controllers? XML comments? another way?) I've tried editing the specification in 'Swagger Editor' but don't see how this can be the way to go since this gets re-generated on every application startup.
I've read the NSwag documentation but that seems to be all about adding the ASP.NET Core middleware, which I already have configured.
Edit:
I now have a description at the top of the page, and have been able to add an example with the remarks tag in XML comments - is there a more elegant way to do this rather than using XML comments?
A description at the top of the page
To customize the API info and description using Nswag, in the Startup.ConfigureServices method, a configuration action passed to the AddSwaggerDocument method adds information such as the author, license, and description:
services.AddSwaggerDocument(config =>
{
config.PostProcess = document =>
{
document.Info.Version = "v1";
document.Info.Title = "ToDo API";
document.Info.Description = "A simple ASP.NET Core web API";
document.Info.TermsOfService = "None";
document.Info.Contact = new NSwag.OpenApiContact
{
Name = "Shayne Boyer",
Email = string.Empty,
Url = "https://twitter.com/spboyer"
};
document.Info.License = new NSwag.OpenApiLicense
{
Name = "Use under LICX",
Url = "https://example.com/license"
};
};
});
The Swagger UI displays the version's information as below:
A summary/description for each endpoint Example parameter inputs for
endpoints that require them Example request body for POST calls An
example access token that can be used only in the swagger
documentation to easily authenticate and be able to try everything out
(a bit like in this example https://petstore.swagger.io/)
You could add the description/example by adding the following elements to the action header.
Use the <summary> element to describe the Endpoint.
Use the <remarks> element to supplements information specified in the <summary> element and provides a more robust Swagger UI. The <remarks> element content can consist of text, JSON, or XML. You could also use it to add sample.
Use the <param> element to add the required parameters. Besides, you could also use the Data annotations attribute with the Model, it will change the UI behavior.
Use the <response> elements to describe response types.
sample code as below:
/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
/// POST /Todo
/// {
/// "id": 1,
/// "name": "Item1",
/// "isComplete": true
/// }
///
/// </remarks>
/// <param name="todoitem"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
#region snippet_CreateActionAttributes
[ProducesResponseType(StatusCodes.Status201Created)] // Created
[ProducesResponseType(StatusCodes.Status400BadRequest)] // BadRequest
#endregion snippet_CreateActionAttributes
#region snippet_CreateAction
[HttpPost]
public ActionResult<TodoItem> Create(TodoItem todoitem)
{
_context.TodoItems.Add(todoitem);
_context.SaveChanges();
return CreatedAtRoute("GetTodo", new { id = todoitem.Id }, todoitem);
}
The Swagger UI now looks as below:
More detail information, please check the following tutorials:
Customize API documentation using NSwag
Customize API info and description using Swashbuckle
Figured this out now, ended up using operation processors to configure the Swagger UI/OpenApi endpoint summary, request examples, path parameter example values and the possible UI response codes
There isn't a lot of documentation online for doing it this way (all i could find was the XML comment way of doing it so this took a lot of trial and error to get this working)
Posting my solution here for anyone else who would prefer not to clutter up their controllers with XML comments.
Apply OpenApiOperationProcessor attribute to the controller action
Create the Operation Processor and code the SwaggerUI customizations
Example values for path parameters can be filled out as so
Lets say I have the following Method:
/// <summary>
/// Just a Method
/// </summary>
[HttpGet()]
[Produces("plain/text")]
public IActionResult Foo() => this.Ok("Some Data..");
Swagger is showing me the following:
Can I achieve the same result, without using <summary> ? Is there an attribute or something I could use?
Iam asking because if I run my project on my machine everything works fine, but if i run it on another it doesnt show the description "Just a Method".
It seems like the XML comments get ignored..
I can't post a single peace of the code so please just tell me if theres a work around so i dont have to use <summary>.
Thanks!
The dotless documentation is quite limited. I can't find much information at all about the configsection options - especially what the "web" attribute does.
Can anyone enlighten me?
The code is normally pretty good documentation for open source projects ;)
Grab a copy of the code and look in dotless.Core > configuration > DotlessConfiguration.cs you will see some handy comments about all the config elements - this is the Web one
/// <summary>
/// Whether this is used in a web context or not
/// </summary>
public bool Web { get; set; }
Admittedly it doesn't tell you a great deal but find the references to that property and you come across only one place in the code where it is used -
if (!configuration.Web)
RegisterLocalServices(pandora);
Which starts to give you a better clue as to what it does which is this
protected virtual void RegisterLocalServices(FluentRegistration pandora)
{
pandora.Service<ICache>().Implementor<InMemoryCache>();
pandora.Service<IParameterSource>().Implementor<ConsoleArgumentParameterSource>();
pandora.Service<ILogger>().Implementor<ConsoleLogger>().Parameters("level").Set("error-level");
pandora.Service<IPathResolver>().Implementor<RelativePathResolver>();
}
So it sets up in memory caching, logging to the console etc (i.e services it uses if not in a web context)
When you add MVC and Razor deployment dependencies I got a lot more assemblies than I expected. But I also get a load of XML files too. Namely:
Microsoft.Web.Infrastructure.xml
System.Web.Helpers.xml
System.Web.Razor.xml
System.Web.WebPages.Deployment.xml
System.Web.WebPages.Razor.xml
WebMatrix.Data.xml
WebMatric.WebData.xml
What are these for? They don't seem to be necessary for a deployed ASP.NET MVC and Razor site to work but I'd like to know what they're for and why or if I actually do need them before I start telling people, "No, you definitely don't need them to run MVC 3 apps." Plus, I'm just interested.
These .xml files contain additional documentation metadata (such as class / method descriptions) that Visual Studio uses when displaying intellisense prompts.
They are not needed at all during build or runtime, and are only used when coding using the Visual Studio IDE.
Namespace.xml files are documentation files. It contains whichever three slash comments you have on classes, methods, properties, ...
You can create from your files, for that go on Project Settings > Build > XML Documentation File. It will extract /// comments from your code to generate the documentation.
Example:
/// <summary>
/// Crops image on the given Point and Size
/// </summary>
/// <param name="img">Current Image</param>
/// <param name="xy">Point X, Y</param>
/// <param name="wh">Size Width, Height</param>
/// <returns></returns>
public static Image Crop(this Image img, Point xy, Size wh)
{
return img.Crop(new Rectangle(xy, wh));
}
Then if you send the DLL to someone they will not necessarily have the code, so they will not have this documentation and VS intelisense will not find any information about the method. With the XML file they can see the method information even without the code.
From MSDN:
Documentation tags
Processing the XML File
Delimiters for Documentation Tags
How to: Use the XML Documentation Features
To clarify these are not needed when deployed to you production servers.
It tells VS what to display in IntelliSense descriptions of things in the corresponding dll
They are supporting files for visual studio internal development. It helps in faster development by providing inline help during coding and referencing as required. They are an aid for Visual Studio.
You can remove them once development phase is over. They will not be needed on deployment!!!