2.9.23 Documentation ConstructsWhen you write programs in Mathematica, there are various ways to document your code. As always, by far the best thing is to write clear code, and to name the objects you define as explicitly as possible. Sometimes, however, you may want to add some "commentary text" to your code, to make it easier to understand. You can add such text at any point in your code simply by enclosing it in matching (* and *). Notice that in Mathematica, "comments" enclosed in (* and *) can be nested in any way. | You can use comments anywhere in the Mathematica code you write. | |
In[1]:=
If[a > b, (* then *) p, (* else *) q]
|
Out[1]=
|
|
| (* text *) | a comment that can be inserted anywhere in Mathematica code |
Comments in Mathematica. There is a convention in Mathematica that all functions intended for later use should be given a definite "usage message", which documents their basic usage. This message is defined as the value of f::usage, and is retrieved when you type ?f.
| f::usage = "text" | define the usage message for a function | | ?f | get information about a function | | ??f | get more information about a function |
Usage messages for functions. | Here is the definition of a function f. | | |
| Here is a "usage message" for f. | |
In[3]:=
f::usage = "f[x] gives the square of x."
|
Out[3]=
|
|
| This gives the usage message for f. | |
 |
| ??f gives all the information Mathematica has about f, including the actual definition. | |
 |
When you define a function f, you can usually display its value using ?f. However, if you give a usage message for f, then ?f just gives the usage message. Only when you type ??f do you get all the details about f, including its actual definition. If you ask for information using ? about just one function, Mathematica will print out the complete usage messages for the function. If you ask for information on several functions at the same time, however, Mathematica will give the name of each function, if possible with a link to its usage information.
| f::usage | main usage message | | f::notes | notes about the function | | f::usage::Language, etc. | messages in a particular language |
Some typical documentation messages. In addition to the usage message, there are some messages such as notes and qv that are often defined to document functions. If you use Mathematica with a text-based interface, then messages and comments are the primary mechanisms for documenting your definitions. However, if you use Mathematica with a notebook interface, then you will be able to give much more extensive documentation in text cells in the notebook.
|
