usage messages - How to create 'help' `?` for a function (as documentation)

I have defined a function foo in some complicated way. But now I would like to add a little documentation that gives the user information on how it is to be used.

I know that the ? symbol could be placed before a built-in function to generate useful information about that built-in function. Is there a way I can add helpful information about my foo function in a similar way?

Answer

You can include usage info using the ::usage tag as follows

foo::usage = "foo[x] takes one argument and returns nothing"

Using Information[foo] or ?foo will display the string in the above message

?foo
(* "foo[x] takes one argument and returns nothing" *)

In addition, in version 8 (and some older versions), using CmdShiftK will complete the template if you start the usage message with foo[x] .... Unfortunately, this doesn't work in version 9.