brittle-fish

9 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 (F#/.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 either of the two console programs 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 (Console.Waterworks Wiki)

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:

let help () =
	let liaison = CWLiaison()
	liaison.RequestHelpDocumentation("Commands")

You will need to add open Console.Waterworks.Attributes on top of that. If you are using the Core version, you will need to add open Console.Waterworks.Core. Attributes instead.

The "Commands" part refers to the name-space of the ConsoleCommands module. So, make sure you adjust it to match what you have used.

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. Here is an example of what a fully attributed command-method looks like.

[<ListCommand>]
[<Description "Appends the named passed into the console onto \"Hello\" and displays it in the console.">]
[<Parameters "name: string">]
[<Usage "> libtest3 \"Craig Oates\"">]
let libtest3 name =
	String.Format("Result: {0}", LibraryTest3 name)

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.

For the sake of completeness, here is a link to the ConsoleCommands modules for the .Net and .Net Core projects:

Table of Contents