Summary of my design interfaces and help documentation are generated.

Summary of my design interfaces and help documentation are generated.

It is very important to find an interface at work. In particular, You need to clearly comment the interface. Colleagues who can call it know what this interface is for and what parameters to pass, here, I made a simple interface and generated help for everyone to learn from each other. If you have any suggestions, I can continue to improve them.

Step 1: create a user interface (clarify the role of this interface)

Define the interface methods in the Add, Delete, Update, and Get modes (I personally think it is best to reload them as much as possible)

Step 2: write comments as detailed as possible in the Method

Write according to the functions, parameter meanings, exceptions, remarks, and return values implemented by the method.

Step 3: Do not use a value like instead of enumeration if the parameter type appears in the interface.

Why do I use enumeration: in actual projects, I may not know what 1 represents at the end of the project. I can solve these problems through enumeration, And the enumeration scalability is also good.

Now let's take a look at the interface I wrote.

1 /// <summary> 2 /// operation on user information 3 /// </summary> 4 public interface IUser 5 {6 /// <summary> 7 // /Add User information 8 // </summary> 9 // <param name = "userInfo"> user entity </param> 10 // <exception cref = "ArgumentNullException "> userInfo is null </exception> 11 // <exception cref =" ArgumentException "> userInfo. id is a Null String </exception> 12 // <exception cref = "ArgumentException"> userInfo. userName is an empty string </exception> 13 // <exception cref = "ArgumentException"> userInfo. passWord is an empty string </exception> 14 // <exception cref = "Exception"> other unknown exceptions </exception> 15 /// <returns> true: added successfully; false: failed to Add </returns> 16 bool Add (UserInfo userInfo ); 17 18 /// <summary> 19 /// delete user 20 /// </summary> 21 // <param name = "userName"> User name </param> 22 // <exception cref = "ArgumentException"> userName is a Null String </exception> 23 // <exception cref = "Exception"> other unknown exceptions </exception> 24 /// <returns> true: false: deletion failed </returns> 25 bool Delete (string userName ); 26 27 /// <summary> 28 // delete users in batches by user name 29 /// </summary> 30 /// <param name = "userNames"> User name (you can one or more) </param> 31 // <exception cref = "ArgumentNullException"> userNames is null </exception> 32 // <exception cref = "ArgumentException"> userNames is not a valid parameter </exception> 33 // <exception cref = "Exception"> other unknown exceptions </exception> 34 // <remarks> Add a transaction, if one of them fails to be deleted, all data will be rolled back </remarks> 35 // <returns> true: Deletion successful; false: failed to Delete </returns> 36 bool Delete (IList <string> userNames ); 37 38 // <summary> 39 // update user information 40 // </summary> 41 // <exception cref = "ArgumentNullException"> userInfo is null </ exception> 42 // <exception cref = "ArgumentException"> userInfo. userName is an empty string </exception> 43 // <exception cref = "Exception"> other unknown exceptions </exception> 44 /// <returns> true: Update successful, false: update failed </returns> 45 bool Update (UserInfo userInfo ); 46 47 // <summary> 48 // obtain the user information according to the user name 49 // </summary> 50 // <exception cref = "ArgumentException"> userName is blank string </exception> 51 // <exception cref = "Exception"> other unknown exceptions </exception> 52 // <returns> returns a user message that can be null </returns> 53 UserInfo Get (string userName ); 54 55 // <summary> 56 // obtain batch user information by user name 57 // </summary> 58 // <param name = "userNames"> User name (can be single or multiple) </param> 59 // <exception cref = "ArgumentNullException"> userNames is null </exception> 60 // <exception cref = "ArgumentException"> userNames is not a valid parameter </exception> 61 // <exception cref = "Exception"> other unknown exceptions </exception> 62 // <remarks> If the returned result is null, no user is returned. result set of </remarks> 63 // <returns> Get user set </returns> 64 IList <UserInfo> Get (IList <string> userNames ); 65 66 // <summary> 67 // obtain the user information based on the title type 68 // </summary> 69 // <param name = "professional"> </ param> 70 // <exception cref = "ArgumentOutOfRangeException"> the professional enumeration is out of the range </exception> 71 // <exception cref = "Exception"> other unknown exceptions </ exception> 72 // <returns> Get user set </returns> 73 IList <UserInfo> Get (UserEnum. professionalType professional); 74}User Interface

Step 4: implement this interface

It is difficult to find out the project after the project goes online. Therefore, we must add the log system, so I added an exception to the project, then, you can use the log to find out where the problem occurs (no function is implemented)

1 /// <summary> 2 /// Implement User-related operations 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. invalid Id "); 14 if (string. isNullOrEmpty (userInfo. userName) 15 throw new ArgumentException ("userInfo. invalid UserName "); 16 if (String. isNullOrEmpty (userInfo. passWord) 17 throw new ArgumentException ("userInfo. invalid PassWord "); 18 return false; 19} 20 catch 21 {22 throw new Exception (" other unknown exceptions "); 23} 24} 25 26 public bool Delete (string userName) 27 {28 try 29 {30 if (string. isNullOrEmpty (userName) 31 throw new ArgumentException ("invalid UserName"); 32 return false; 33} 34 catch 35 {36 throw new Exception ("other unknown exceptions "); 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 invalid"); 48 return false; 49} 50 catch 51 {52 throw new Exception ("other unknown exceptions "); 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. invalid UserName "); 64 return false; 65} 66 catch 67 {68 throw new Exception ("other unknown exceptions"); 69} 70 71} 72 73 public UserInfo Get (string userName) 74 {75 try 76 {77 if (string. isNullOrEmpty (userName) 78 throw new ArgumentException ("invalid UserName"); 79 return null; 80} 81 catch {82 throw new Exception ("other unknown exceptions "); 83} 84} 85 86 public IList <UserInfo> Get (IList <string> userNames) 87 {88 try 89 {90 if (userNames = null) 91 throw new Ar GumentNullException ("userNames"); 92 if (! UserNames. any () 93 throw new ArgumentException ("userNames invalid"); 94 return null; 95} 96 catch {97 throw new Exception ("other unknown exceptions "); 98} 99 100} 101 102 public IList <UserInfo> Get (UserEnum. professionalType professional) 103 {104 try105 {106 if (professional> = (UserEnum. professionalType) 4) 107 throw new ArgumentOutOfRangeException ("professional"); 108 return null; 109} 110 catch {111 throw new Exception ("other unknown exceptions "); 112} 113 114} 115}Implementation Interface

Step 5: click "Project Properties" and find "generate" Check xml document file ", as shown in

Step 6: DownloadSandcastle Help File BuilderThen install the tool. After the installation is successful, findSandcastle Help File BuilderCreate a project, as shown in figure

 

Step 7: Find the generated dll and xml files and import them as shown in Figure

Step 8: Click Generate to generate a help document.

Results of generating help documents

 

The above is the overall effect. You are welcome to discuss it with each other.