17

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?

QuantumDot
  • 19,601
  • 7
  • 45
  • 121

2 Answers2

20

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.

Community
  • 1
rm -rf
  • 88,781
  • 21
  • 293
  • 472
  • It is safe to say that Mathematica's ::usage and template system is best described as "kludgy". For the benefit of others I provide a link to a question that summarizes the various problems and possible workarounds: http://mathematica.stackexchange.com/questions/58669/what-is-the-status-of-usage-and-templates-in-mathematica-v10-1 – QuantumDot Feb 07 '16 at 15:45
  • How do I change the message in the floating message which appears when the function name is typed? – Gabriel Sandoval Jun 05 '20 at 23:55
7

The simplest way for a short documentation is by adding a usage to a function, as described in the other answer above.

For a more in depth documentation (as in the Mathematica help) you can use Wolfram Workbench, a tutorial can be found there
http://www.wolfram.co.uk/products/workbench/.

Alternatively you can have a look at this answer.
https://stackoverflow.com/questions/6574710/integrating-notebooks-to-mathematicas-documentation-center

Community
  • 1
faysou
  • 10,999
  • 3
  • 50
  • 125