我的设计接口总结以及生成帮助文档

前言：在工作发现接口至关重要，特别需要把接口的注释写清楚，能调用的同事知道这个接口是干嘛用的，要传递什么参数等，在这里我做了一个简单的接口并生成帮助帮助，供大家相互学习，有好的可以提出来我继续改进。

第一步：建立一个用户接口（明确这个接口的作用）

按照Add，Delete，Update，Get模式来定义接口的方法（我个人觉得尽可能的重载）

第二步：方法中写出尽可能详尽的注释

按照方法实现的功能，参数意思，异常，备注，返回值等来写

第三步：接口中如果出现参数为类型的时候千万不要用1,2这样的数值代替尽可能用枚举

为什么用枚举：因为在实际项目中可能做到最后的时候自己都不知道1代表什么2代表什么，通过枚举就能解决这些问题，而且枚举扩展性也很好

现在我们看一下我写的接口

/// <summary>
/// 实现用户相关操作
/// </summary>
public class User:IUser {

public bool Add(UserInfo userInfo)
{
try
{
if (userInfo == null)
throw new ArgumentNullException("userInfo");
if (string.IsNullOrEmpty(userInfo.Id))
throw new ArgumentException("userInfo.Id无效");
if (string.IsNullOrEmpty(userInfo.UserName))
throw new ArgumentException("userInfo.UserName无效");
if (string.IsNullOrEmpty(userInfo.PassWord))
throw new ArgumentException("userInfo.PassWord无效");
return false;
}
catch
{
throw new Exception("其他未知异常");
}
}

public bool Delete(string userName)
{
try
{
if (string.IsNullOrEmpty(userName))
throw new ArgumentException("UserName无效");
return false;
}
catch
{
throw new Exception("其他未知异常");
}
}

public bool Delete(IList<string> userNames)
{
try
{
if (userNames == null)
throw new ArgumentNullException("userNames");
if (!userNames.Any())
throw new ArgumentException("userNames无效");
return false;
}
catch
{
throw new Exception("其他未知异常");
}
}

public bool Update(UserInfo userInfo)
{
try
{
if (userInfo == null)
throw new ArgumentNullException("userInfo");
if (string.IsNullOrEmpty(userInfo.UserName))
throw new ArgumentException("userInfo.UserName无效");
return false;
}
catch
{
throw new Exception("其他未知异常");
}

}

public UserInfo Get(string userName)
{
try
{
if (string.IsNullOrEmpty(userName))
throw new ArgumentException("UserName无效");
return null;
}
catch {
throw new Exception("其他未知异常");
}
}

public IList<UserInfo> Get(IList<string> userNames)
{
try
{
if (userNames == null)
throw new ArgumentNullException("userNames");
if (!userNames.Any())
throw new ArgumentException("userNames无效");
return null;
}
catch {
throw new Exception("其他未知异常");
}

}

public IList<UserInfo> Get(UserEnum.ProfessionalType professional)
{
try
{
if (professional >= (UserEnum.ProfessionalType)4)
throw new ArgumentOutOfRangeException("professional");
return null;
}
catch {
throw new Exception("其他未知异常");
}

}
}

实现接口
第五步：点击项目属性，找到生成勾选xml文档文件如下图



第六步：下载一个Sandcastle Help File Builder 然后安装，安装成功以后，找到Sandcastle Help File Builder新建一个项目如下图





第七步：找到生成的dll和xml文件然后导入如下图



第八步：点击生成按钮就可以生成一篇帮助文档了



生成帮助文档的效果



以上就是整个效果，大家有好的欢迎相互讨论。