populate Using the Help Attributes page.

master
Craig Oates 5 years ago
parent
commit
8ec3e50744
  1. 48
      Using-the-Help-Attributes.md

48
Using-the-Help-Attributes.md

@ -0,0 +1,48 @@
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.
SCREENSHOT OF HELP SECTION AT RUN-TIME.
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 (Console.Waterworks Wiki)](https://gitlab.com/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;
```f#
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.
```f#
[<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;
- [BrittleFish ConsoleCommands.fs (.Net)](https://gitlab.com/craig.oates/Brittle-Fish/blob/master/BrittleFish/ConsoleCommands.fs)
- [BrittleFishCore ConsoleCommands.fs (Core)](https://gitlab.com/craig.oates/Brittle-Fish/blob/master/BrittleFishCore/ConsoleCommands.fs)
Loading…
Cancel
Save