C#规范类库的注释,生成xml类库注释提示文件
当我们创建一个dll给其他人使用时,为了方便,增加合适的注释。这是一种很好的代码规范,应该养成这种生成注释的习惯。
右键 dll类库项目,选择 属性,切换到 “生成” 选项,在“输出”分组框里面 勾选 XML文档文件,即可。
生成dll后,将同时生成一个xml注释文件。
一、新建类库:StandardLibraryComment,选择.net framework 4.5
1.将默认的Class1.cs重命名为Employee.cs。
Employee.cs源程序如下:
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
namespace StandardLibraryComment
{
/// <summary>
/// 员工信息类
/// Author:斯内科
/// 2020-10-09
/// </summary>
public class Employee
{
/// <summary>
/// 编号
/// </summary>
public int Id { get; set; }
/// <summary>
/// 姓名
/// </summary>
[DisplayName("员工姓名")]
public string Name { get; set; }
/// <summary>
/// 地址
/// </summary>
public string Address { get; set; }
/// <summary>
/// 入职日期
/// </summary>
public DateTime JoinDate { get; set; }
/// <summary>
/// 打印员工信息
/// </summary>
public void PrintMessage()
{
Console.WriteLine($"编号:{Id},姓名:{Name},地址:{Address},入职日期:{JoinDate}");
}
}
}
2.新建测试类TestClass.cs
TestClass.cs源程序如下:
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
namespace StandardLibraryComment
{
/// <summary>
/// 测试类
/// Author:斯内科
/// 2020-10-09
/// </summary>
public class TestClass
{
/// <summary>
/// 加法:计算两个数字之和
/// </summary>
/// <param name="x">第一个整数</param>
/// <param name="y">第二个整数</param>
/// <returns>返回两数之和</returns>
public static int Add(int x, int y = 2)
{
return x + y;
}
/// <summary>
/// 减法:计算两个数字之差
/// </summary>
/// <param name="x">被减数</param>
/// <param name="y">减数</param>
/// <returns>返回两数之差</returns>
public static int Subtract(int x, int y)
{
return x - y;
}
/// <summary>
/// 获取数组的最大数以及最大数所在的索引
/// </summary>
/// <param name="array">数组</param>
/// <param name="maxIndex">输出最大值的所在的索引</param>
/// <returns></returns>
public int GetMaxNumber(int[] array, out int maxIndex)
{
if (array == null || array.Length == 0)
{
Console.WriteLine("数组不能为null,数组的长度也不能为,暂定返回值为-1");
maxIndex = -1;
return -1;
}
int max = array[0];
maxIndex = 0;
for (int i = 1; i < array.Length; i++)
{
if (max < array[i])
{
maxIndex = i;
max = array[i];
}
}
return max;
}
/// <summary>
/// 获得不定项数组的长度
/// </summary>
/// <param name="array">不定项数组</param>
/// <returns></returns>
public int GetVaryArrayLength(params int[] array)
{
if (array == null)
{
return 0;
}
return array.Length;
}
/// <summary>
/// 测试带ref的参数
/// </summary>
/// <param name="inParameter"></param>
/// <param name="refParameter"></param>
public void TestReference(int inParameter, ref int refParameter)
{
inParameter = 5;
refParameter = 2;
Console.WriteLine("参数默认为输入参数,如:inParameter,不会改变原来的值.\r\n带ref或者out的参数是引用参数,如:refParameter,可以改变原来的值.");
}
/// <summary>
/// 私有方法无法通过反射得到该方法的信息
/// </summary>
private void PrivateMethod()
{
Console.WriteLine("私有方法");
}
}
}
☆关键操作:
右键类库项目StandardLibraryComment,选择“属性”。切换到“生成”项,勾选XML文档文件。
然后 右键 类库项目StandardLibraryComment,选择“生成”,将在bin\debug目录下生成三个文件:
StandardLibraryComment.xml就是相应的类和方法的注释说明。
二、新建控制台项目StandardLibraryProduceDemo
1.新建文件夹Dll,在文件夹中添加刚生成的两个文件 StandardLibraryComment.dll 和 StandardLibraryComment.xml。
右键StandardLibraryProduceDemo,添加引用,浏览(注:直接添加 引用 --项目 StandardLibraryComment 也是可以的,这里暂不考虑。),添加对StandardLibraryComment的引用:
在默认的Main函数中我们可以看到类和方法的代码提示:
方法和参数的提示:
2.在默认的Program.cs输入测试代码:
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
namespace StandardLibraryProduceDemo
{
class Program
{
static void Main(string[] args)
{
int result = StandardLibraryComment.TestClass.Subtract(100, 22);
Console.WriteLine($"测试两数之差的结果:{result}");
StandardLibraryComment.TestClass testClass = new StandardLibraryComment.TestClass();
int varyLength = testClass.GetVaryArrayLength(3, 8, 28, 2);
Console.WriteLine($"测试获得不定项数组的长度:{varyLength}");
Console.ReadLine();
}
}
}