console.waterworks

7 Using the Help Attributes

Escape

To help users discover features within your console program, Console.Waterworks (C.W.) 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 CW-Console (press F5) 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.

There are four attributes in total. They are:

List Command: Show command at run-time.
Description: Describes what the command does.
Usage: Provides an example of how to use the command.
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 (in the "As Source Code" section)

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:

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.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. 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.

[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-Console. Hopefully, seeing more realistic examples will help reduce any confusion. The link is as follows:

ConsoleCommands.cs

Table of Contents

As Source Code

Console.Waterworks

CW-Console

CW-Tests

As a NuGet