Assume, i have a method which parameters are classes with already defined documentation:
/// <summary>
/// Get criterion from table.
/// </summary>
/// <param name="plySide"></param>
/// <param name="criterionType"></param>
/// <returns></returns>
public Criterion GetCriterion(PlySide plySide, CriterionType criterionType)
{
// some code
}
PlySide class has it's own xml-documentation:
/// <summary>
/// Sides of monoply.
/// </summary>
public enum PlySide
{
// some code
}
As you can see in GetCriterion method i didn't define any doc for the plySide param tag.
My question is should i duplicate description of a parameter or should i remove param tags?
The PlySide documentation will describe what the type is.
The plySide documentation should describe what role that parameter plays within the GetCriterion method.
Those will usually be subtly (or not so subtly) different.
You shouldn't duplicate it but give a context aware description of the parameter. In your case it could be something like this (perhaps it's toally wrong, but I don't know the implementation and intention of your method):
/// <summary>
/// Get criterion from table.
/// </summary>
/// <param name="plySide">Monopoly side to get criterion for</param>
/// <param name="criterionType">Criterion to get for the given monopoly side</param>
/// <returns></returns>
public Criterion GetCriterion(PlySide plySide, CriterionType criterionType)
{
// some code
}
Related
I want to use inheritdoc to grab the description of a parameter. So I have:
/// <param name="nameOfParameter">parameter description</param>
MethodName(int nameOfParameter)`
...
/// <summary>
/// <inheritdoc cref="ClassName.MethodName" select="param[#name='nameOfParameter']" />
/// </summary>
AnotherFunc
But AnotherFunc now has the description of MethodName rather than the parameter. Is this possible?
It seems that the select attribute is no longer used in inheritdoc tag. Use path instead:
/// <summary>
/// <inheritdoc cref="ClassName.MethodName" path="/param[#name='nameOfParameter']" />
/// </summary>
void AnotherFunc() { }
UPDATE
The xpath above will also include the inherited <param> tag itself inside the <summary> tag. It's not visible in the Intellisense quick info. But the more appropriate xpath should insert just the contents of the inherited <param> tag:
/// <summary>
/// <inheritdoc cref="MethodName" path="//param[#name='nameOfParameter']/node()" />
/// </summary>
void AnotherFunc() { }
I'm trying to create a documentation response header in a method like this
public Task<CustomObject> AuthUserAsync()
{
}
So, as I understand it should be something like
/// <summary>
/// Description.
/// </summary>
/// <returns>A <see cref="Task"/><<see cref="CustomObject"/>> representing the operation.</returns>
public Task<CustomObject> AuthUserAsync()
{
}
But I'm unable to see the documentation when hover the mouse on the method
Any ideas?
The proper syntax to use a template argument in a documentation header is:
/// <summary>
/// Description.
/// </summary>
/// <returns>A <see cref="Task{TResult}"/> representing the operation.</returns>
public Task<CustomObject> AuthUserAsync()
{
}
Note that the angle brackets are replaced by {}, because angle brackets would make the XML invalid at that point. You cannot put Task{int} there, even though that would be more exact, because Task<int> is not a type you can create a reference to. If you write it without the cref, you can do
/// <returns>A Task>int< representing the operation.</returns>
You are still not allowed to use literal < or > characters, though.
Suppose I have a method as follows:
/// <summary>
/// Here I want to reference the parameter <see cref="personId"/>.
/// </summary>
/// <param name="personId">
/// The person id.
/// </param>
/// <returns>
/// The <see cref="Person"/>.
/// </returns>
public Person GetPerson(int personId)
{
}
When I publish my XML documentation using Sandcastle, the cref:
<see cref="personId"/>
gets converted to [!:personId].
The warning in Sandcastle is:
Unknown reference link target
Any advice?
Use <paramref>
<paramref name="personId"/>
For a function parameter, I want to use a list of options in the code documentation.
For the <summary> tag, this is no problem (Microsoft Docs). But how do I make a bullet list for a <param> tag? The example below doesn't create a list in the quickview window while programming:
<param name="Type list">
<list type= "bullet">
<item><description>Item description</description></item>
</list>
</param>
This works fine.
I tried this code:
public class Program
{
/// <summary>The summary</summary>
/// <param name="args">
/// The command-line arguments.
/// <list type="bullet">
/// <item><description>Item 1</description></item>
/// <item><description>Item 2</description></item>
/// <item><description>Item 3</description></item>
/// </list>
/// </param>
public static void Main(string[] args)
{
}
}
Then I used Sandcastle to produce a help file which looks like this:
As you can see, the bulleted list appears correctly for the parameter.
This is how Resharper shows the tooltip:
Bullet list didn't work for me, perhaps because I want to add it for a class property. Use <para> for that, like this:
public class Program
{
/// <summary>
/// Main comment.
/// <para>List 1 :</para>
/// <para>- Item 1</para>
/// <para>- Item 2</para>
/// <para>- Item 3</para>
/// <para>- Item..n</para>
/// </summary>
public string property1 { get; set; }
}
If you user xml doc with Swagger, it will ignore tag, instead you should use "-"
/// my list:
/// option 1
/// option 2
///
/// other staff
In the below code in xml documentations there is mismatch between the names of parameters in method's arguments and name of parameters in xml documentation. Is there any way to auto correct the xml documentation signature or any feature provided in resharper to auto correct the xml documentation.
#region Get Images
/// <summary>
/// Get Images
/// </summary>
/// <param name="par1"></param>
/// <param name="par2"></param>
/// <returns></returns>
public Collection<UserImage> GetImages()
{
return GetImages("");
}
/// <summary>
/// Get Images
/// </summary>
/// <param name="par1"></param>
/// <param name="par2"></param>
/// <returns></returns>
public Collection<UserImage> GetImages(string imageType)
{
return GetImages(0, imageType);
}
/// <summary>
/// Get Images
/// </summary>
/// <param name="par1"></param>
/// <param name="par2"></param>
/// <returns></returns>
public Collection<UserImage> GetImages(int imageId)
{
return GetImages(imageId, "");
}
/// <summary>
/// Get Images
/// </summary>
/// <param name="par1"></param>
/// <param name="par2"></param>
/// <returns></returns>
public Collection<UserImage> GetImages(int imageId,string imageType)
{
return null;
}
#endregion
For example i want the method with xml documentation like this:
/// <summary>
/// Get Images
/// </summary>
/// <param name="imageId"></param>
/// <param name="imageType"></param>
/// <returns></returns>
public Collection<UserImage> GetImages(int imageId,string imageType)
{
return null;
}
#endregion
GhostDoc will do this for you. After installation you get a new context menu item in VS 'Document this' (and a corresponding keyboard shortcut).
If no XML comments are present, it will add them. If they are already present, they should get updated as you require.
http://submain.com/products/ghostdoc.aspx
The only way I know to "auto correct" xml with R# is to delete the existing xml documentation and hit /// again. Sorry I don't have a better answer.
I believe it's not possible because R# doesn't what need to correct the xml documentation or method signature.