craig.oates
/
console.waterworks.core
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

master
Craig Oates 4 years ago
parent
494fc9185f
commit
15c9e930ff
1 changed files with 53 additions and 53 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 106
      Using-the-Help-Attributes.md

106
Using-the-Help-Attributes.md
Unescape

@ -1,53 +1,53 @@
To help users discover features within your console program, Console.Waterworks.Core (C.W.C.) provides a run-time "help" section. It does this by using the (C#/.Net) attributes you attach to your command-methods. It is, also, optional. So, you do not need to decorate your command-methods if you do not want to. If you have cloned this repository, you can see this in action. To do so, run console program and enter "Help" into the prompt. You should see a list of available commands, a description of what they do and how to use them.
![screenshot of help at run-time](run-time-help.gif)
There are four attributes in total. They are:
1. List Command: Show command at run-time.
2. Description: Describes what the command does.
3. Usage: Provides an example of how to use  the command.
4. Parameters: Lists out the commands argument list and their types.
For more information on the "help" attributes, please refer to the following link:
- [Help Attributes Wiki Page (main Console.Waterworks wiki)](https://git.abbether.net/craig.oates/Console.Waterworks/wikis/The-%22Help%22-Attributes)
To set-up the "help" section , you must create a command-method first. You can use any name you want. For example, I usually call it `help`.
Within the "help" command-method, enter the following code:
```c#
public static string help()
{
CW_Liaison liaison = new CW_Liaison();
// Don't forget your name-space for your ConsoleCommands class
return liaison.RequestHelpDocumentation("YOUR NAME-SPACE HERE");
}
```
You will need to add `using Console.Waterworks.Core.Attributes` to your `ConsoleCommands` class if you decide to use add this feature.
**You must enter the name-space of your `ConsoleCommands` class into the `RequestHelpDocumentation` method. Without it, you will get a run-time error.**
If you run your console program and type "help", you should find nothing happened. Do not worry, this is usually a sign you have successfully set-up the C.W.C. help section. It, also, means you can start decorating your command-methods with attributes.
When adding attributes to your command-methods, you can add them in any order. Below is an example of what a fully attributed command-method looks like.
```c#
[ListCommand()]
[Description("Outputs a message indicating this program is running okay.")]
[Parameters("None")]
[Usage("> Test")]
public static string Test()
{
// You can add your code here...
return "Test command working as expected.";
}
```
A nice side-effect of the attributes is your command-methods are "self-documented". And, because this bit of code is used by the end-user, there is an extra incentive to keep the documentation up-to-date. Who said I'm not an optimist...
For the sake of completeness, I have provided a link to the `ConsoleCommands` class in CW_Core_Console. Hopefully, seeing more realistic examples will help reduce any confusion. The link is as follows:
- [ConsoleCommands.cs](https://git.abbether.net/craig.oates/Console.Waterworks.Core/blob/master/CW_Core_Console/ConsoleCommands.cs)
To help users discover features within your console program, Console.Waterworks.Core (C.W.C.) provides a run-time "help" section. It does this by using the (C#/.Net) attributes you attach to your command-methods. It is, also, optional. So, you do not need to decorate your command-methods if you do not want to. If you have cloned this repository, you can see this in action. To do so, run console program and enter "Help" into the prompt. You should see a list of available commands, a description of what they do and how to use them.
![screenshot of help at run-time](run-time-help.gif)
There are four attributes in total. They are:
1. List Command: Show command at run-time.
2. Description: Describes what the command does.
3. Usage: Provides an example of how to use  the command.
4. Parameters: Lists out the commands argument list and their types.
For more information on the "help" attributes, please refer to the following link:
- [Help Attributes Wiki Page (main Console.Waterworks wiki)](https://git.abbether.net/craig.oates/Console.Waterworks/wiki/The-%22Help%22-Attributes)
To set-up the "help" section , you must create a command-method first. You can use any name you want. For example, I usually call it `help`.
Within the "help" command-method, enter the following code:
```c#
public static string help()
{
CW_Liaison liaison = new CW_Liaison();
// Don't forget your name-space for your ConsoleCommands class
return liaison.RequestHelpDocumentation("YOUR NAME-SPACE HERE");
}
```
You will need to add `using Console.Waterworks.Core.Attributes` to your `ConsoleCommands` class if you decide to use add this feature.
**You must enter the name-space of your `ConsoleCommands` class into the `RequestHelpDocumentation` method. Without it, you will get a run-time error.**
If you run your console program and type "help", you should find nothing happened. Do not worry, this is usually a sign you have successfully set-up the C.W.C. help section. It, also, means you can start decorating your command-methods with attributes.
When adding attributes to your command-methods, you can add them in any order. Below is an example of what a fully attributed command-method looks like.
```c#
[ListCommand()]
[Description("Outputs a message indicating this program is running okay.")]
[Parameters("None")]
[Usage("> Test")]
public static string Test()
{
// You can add your code here...
return "Test command working as expected.";
}
```
A nice side-effect of the attributes is your command-methods are "self-documented". And, because this bit of code is used by the end-user, there is an extra incentive to keep the documentation up-to-date. Who said I'm not an optimist...
For the sake of completeness, I have provided a link to the `ConsoleCommands` class in CW_Core_Console. Hopefully, seeing more realistic examples will help reduce any confusion. The link is as follows:
- [ConsoleCommands.cs](https://git.abbether.net/craig.oates/Console.Waterworks/src/branch/master/Console.Waterworks/CW_Console/ConsoleCommands.cs)

Write Preview
Loading…
Cancel
Save