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
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() { }
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
}
Currently I'm documenting Lists as follows:
/// <summary>
/// Returns a <see cref="List{T}" /> of type <see cref="Person" />.
/// </summary>
public List<Person> ListExample()
{
}
The following does not seem to be interpreted by Sandcastle:
/// <summary>
/// Returns a <see cref="List{Person}" />.
/// </summary>
public List<Person> ListExample()
{
}
Any advice?
Thanks.
I'm a beginner in using the 3-tier approach in development, i got many drop down lists in my application each consisting of 4 or 5 choices. If i stored this data in my database, then according to my understanding of 3-tier approach, i need to create a Data access class and a business class for each of the lists. This means i need to create almost 40 classes for 20 drop down lists, this surely does not sound practical.
Is there a better way to design drop down lists or to store the DDL data in my application ?
You can have a generic binding class as following.
/// <summary>
/// Common DropDown model
/// </summary>
public class SelectListModel
{
/// <summary>
/// Gets or sets the value.
/// </summary>
/// <value>
/// The value.
/// </value>
public int Value { get; set; }
/// <summary>
/// Gets or sets the item.
/// </summary>
/// <value>
/// The item.
/// </value>
public string Item { get; set; }
/// <summary>
/// Gets or sets a value indicating whether this instance is selected.
/// </summary>
/// <value>
/// <c>true</c> if this instance is selected; otherwise, <c>false</c>.
/// </value>
public bool IsSelected { get; set; }
}
You can bind any dropdown data into this model and return it to the view.
private void DropwonlistBind(DropDownList DDLName)
{
DDLName.Datasource="YourSouce";
DDLName.DataTextField="TextField";
DDLName.DataValueField="IDField";
DDLName.Databind();
}
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.