前言：在工作发现接口至关重要，特别需要把接口的注释写清楚，能调用的同事知道这个接口是干嘛用的，要传递什么参数等，在这里我做了一个简单的接口并生成帮助帮助，供大家相互学习，有好的可以提出来我继续改进。
第一步：建立一个用户接口（明确这个接口的作用）
按照Add，Delete，Update，Get模式来定义接口的方法（我个人觉得尽可能的重载）
第二步：方法中写出尽可能详尽的注释
按照方法实现的功能，参数意思，异常，备注，返回值等来写
第三步：接口中如果出现参数为类型的时候千万不要用1,2这样的数值代替尽可能用枚举
为什么用枚举：因为在实际项目中可能做到最后的时候自己都不知道1代表什么2代表什么，通过枚举就能解决这些问题，而且枚举扩展性也很好
现在我们看一下我写的接口
1 /// <summary> 2 /// 关于用户信息的操作 3 /// </summary> 4 public interface IUser 5 { 6 /// <summary> 7 /// 添加用户信息 8 /// </summary> 9 /// <param name="userInfo">用户实体</param> 10 /// <exception cref="ArgumentNullException">userInfo为null</exception> 11 /// <exception cref="ArgumentException">userInfo.Id为空字符串</exception> 12 /// <exception cref="ArgumentException">userInfo.UserName为空字符串</exception> 13 /// <exception cref="ArgumentException">userInfo.PassWord为空字符串</exception> 14 /// <exception cref="Exception">其他未知异常</exception> 15 /// <returns>true：添加成功 false：添加失败</returns> 16 bool Add(UserInfo userInfo); 17 18 /// <summary> 19 /// 根据用户名删除用户 20 /// </summary> 21 /// <param name="userName">用户名</param> 22 /// <exception cref="ArgumentException">userName为空字符串</exception> 23 /// <exception cref="Exception">其他未知异常</exception> 24 /// <returns>true：删除成功 false：删除失败</returns> 25 bool Delete(string userName); 26 27 /// <summary> 28 /// 根据用户名批量删除用户 29 /// </summary> 30 /// <param name="userNames">用户名（可以单个也可以多个）</param> 31 /// <exception cref="ArgumentNullException">userNames为null</exception> 32 /// <exception cref="ArgumentException">userNames不是有效参数</exception> 33 /// <exception cref="Exception">其他未知异常</exception> 34 ///<remarks>加入事物，如果其中一条未能删除成功，所有数据进行回滚</remarks> 35 /// <returns>true：删除成功 false：删除失败</returns> 36 bool Delete(IList<string> userNames); 37 38 /// <summary> 39 /// 更新用户信息 40 /// </summary> 41 /// <exception cref="ArgumentNullException">userInfo为null</exception> 42 /// <exception cref="ArgumentException">userInfo.UserName为空字符串</exception> 43 /// <exception cref="Exception">其他未知异常</exception> 44 /// <returns>true：更新成功 false：更新失败</returns> 45 bool Update(UserInfo userInfo); 46 47 /// <summary> 48 /// 根据用户名获取用户信息 49 /// </summary> 50 /// <exception cref="ArgumentException">userName为空字符串</exception> 51 /// <exception cref="Exception">其他未知异常</exception> 52 /// <returns>返回一条用户信息可为null</returns> 53 UserInfo Get(string userName); 54 55 /// <summary> 56 /// 根据用户名获取批量用户信息 57 /// </summary> 58 /// <param name="userNames">用户名（可以单个也可以多个）</param> 59 /// <exception cref="ArgumentNullException">userNames为null</exception> 60 /// <exception cref="ArgumentException">userNames不是有效参数</exception> 61 /// <exception cref="Exception">其他未知异常</exception> 62 /// <remarks>如果返回结果为空则返回一条没有任何用户的结果集</remarks> 63 /// <returns>获取用户集</returns> 64 IList<UserInfo> Get(IList<string> userNames); 65 66 /// <summary> 67 /// 根据职称类型获取用户信息 68 /// </summary> 69 /// <param name="professional"></param> 70 /// <exception cref="ArgumentOutOfRangeException">professional枚举不在范围内</exception> 71 /// <exception cref="Exception">其他未知异常</exception> 72 /// <returns>获取用户集</returns> 73 IList<UserInfo> Get(UserEnum.ProfessionalType professional); 74 }
第四步：实现这个接口
因为项目一上线错误出现以后就很难发现，所以我们一定要加入日志系统，所以在项目中我加入了抛异常，然后通过日志就知道问题出现在哪里（没有实现功能）
1 /// <summary> 2 /// 实现用户相关操作 3 /// </summary> 4 public class User:IUser { 5 6 public bool Add(UserInfo userInfo) 7 { 8 try 9 { 10 if (userInfo == null) 11 throw new ArgumentNullException("userInfo"); 12 if (string.IsNullOrEmpty(userInfo.Id)) 13 throw new ArgumentException("userInfo.Id无效"); 14 if (string.IsNullOrEmpty(userInfo.UserName)) 15 throw new ArgumentException("userInfo.UserName无效"); 16 if (string.IsNullOrEmpty(userInfo.PassWord)) 17 throw new ArgumentException("userInfo.PassWord无效"); 18 return false; 19 } 20 catch 21 { 22 throw new Exception("其他未知异常"); 23 } 24 } 25 26 public bool Delete(string userName) 27 { 28 try 29 { 30 if (string.IsNullOrEmpty(userName)) 31 throw new ArgumentException("UserName无效"); 32 return false; 33 } 34 catch 35 { 36 throw new Exception("其他未知异常"); 37 } 38 } 39 40 public bool Delete(IList<string> userNames) 41 { 42 try 43 { 44 if (userNames == null) 45 throw new ArgumentNullException("userNames"); 46 if (!userNames.Any()) 47 throw new ArgumentException("userNames无效"); 48 return false; 49 } 50 catch 51 { 52 throw new Exception("其他未知异常"); 53 } 54 } 55 56 public bool Update(UserInfo userInfo) 57 { 58 try 59 { 60 if (userInfo == null) 61 throw new ArgumentNullException("userInfo"); 62 if (string.IsNullOrEmpty(userInfo.UserName)) 63 throw new ArgumentException("userInfo.UserName无效"); 64 return false; 65 } 66 catch 67 { 68 throw new Exception("其他未知异常"); 69 } 70 71 } 72 73 public UserInfo Get(string userName) 74 { 75 try 76 { 77 if (string.IsNullOrEmpty(userName)) 78 throw new ArgumentException("UserName无效"); 79 return null; 80 } 81 catch { 82 throw new Exception("其他未知异常"); 83 } 84 } 85 86 public IList<UserInfo> Get(IList<string> userNames) 87 { 88 try 89 { 90 if (userNames == null) 91 throw new ArgumentNullException("userNames"); 92 if (!userNames.Any()) 93 throw new ArgumentException("userNames无效"); 94 return null; 95 } 96 catch { 97 throw new Exception("其他未知异常"); 98 } 99 100 } 101 102 public IList<UserInfo> Get(UserEnum.ProfessionalType professional) 103 { 104 try 105 { 106 if (professional >= (UserEnum.ProfessionalType)4) 107 throw new ArgumentOutOfRangeException("professional"); 108 return null; 109 } 110 catch { 111 throw new Exception("其他未知异常"); 112 } 113 114 } 115 }
第五步：点击项目属性，找到生成勾选xml文档文件如下图
第六步：下载一个Sandcastle Help File Builder 然后安装，安装成功以后，找到Sandcastle Help File Builder新建一个项目如下图
第七步：找到生成的dll和xml文件然后导入如下图
第八步：点击生成按钮就可以生成一篇帮助文档了
生成帮助文档的效果
以上就是整个效果，大家有好的欢迎相互讨论。