Best Practice to write ::usage for own package functions

Question

I'm writing an own package with Mathematica, that I would like to make available for others. In order to do that (and for my own usage of the package), I would like to write ::usage-strings for all my public functions.

I would like to use a formated string for ::usage in order to refer to some mathematical background in the explanations, e.g. if one of the inputs is a matrix, the ::usage may contain $\mathbf{M}\in\mathbb Z^{d\times d}$ or something like that.

The way I'm generating these up to now is, to take a cell and change it's style to text, then write the text and copy it into the ::usage="..." cell of the package. On saving the package, that gets transformed into the classic commands, like in the following example:

DirichletKernel::usage = "DirichletKernel[\!\(\*StyleBox[\"mM\",\nFontWeight->\"Bold\"]\)]    
  provides a dirichlet kernel with respect to the regular integral matrix mM
  in Fourier coefficients. The same options as for the function \!\(\*
  StyleBox[\"deLaValleePoussinKernel\", \"Code\"]\)\!\(\*
  StyleBox[\"[\", \"Code\"]\)\!\(\*StyleBox[\"]\", \"Code\"]\) apply.";

Where the last part at least seems a little messed up.

There are two questions arising:

1) Is there an easier way to write such a usage message? because if I want to change something, I usually have to write the whole text again, because the format is quite verbose. What workflow do you use to write ::usage messages?

2) Sometimes the copy&paste stuff generates errors (hmpf, if you want to demonstrate something, of course, it works, I'll edit this, if I can get the actual message), that occur in the message window. Since Mathematica 9 that already happens if the autocomplete-box occurs. So what has to be taken into account copying formated cells (text with math formula and e.g. bold face and code parts) into strings - in order to not get messed up (erroneous) strings?

Answer 1

In Mathematica, usage messages are typically for conveying a short description of how to call the function. Your text that talks about the options would be better placed in package documentation in the Details section. You can use Wolfram Workbench to generate package documentation that shows up in the Documentation Center.

Answer 2

First, I want to say that I don't like heavily formatted usages messages. A usage message should be a short description in a form of a simple ascii message, so that it can be viewed even without a front-end.

Nevertheless, let me try to give you a hint here. I would do the following:

1. write your usage messages in a separate package-notebook in the Mathematica front-end, where you can look at it as formatted text and not as string-expression.
2. store this notebook as package Usage.m side by side to your implementation package.
3. load this package in the Kernel/init.m of you package.

1. Package notebook

When you use the Mathematica front-end for editing, you can input any special box form without caring about the underlying, complicated string-expression.

2. Store the package

After you saved the package, it is stored on disk as

(* ::Package:: *)

BeginPackage["YourContext`"];
f::usage="f[x] calculates \!\(\*SubsuperscriptBox[\(\[Integral]\), \(min\),\
  \(max\)]\)f[x]\[DifferentialD]x."
EndPackage[];

but you don't have to care about it, because 1. you never see this in e.g. the Wolfram Workbench because your implementation is in another file and 2. you edit this package always in the front-end.

3. Loading the usages

Just load this in the init.m. It's probably the best, when you look how it is done in the VectorFieldPlots package in the AddOns/Packages path. Their init.m looks like

(* initialization file for the vector field plots package VectorFieldPlots` *)

Get["VectorFieldPlots`Usage`"];
Get["VectorFieldPlots`VectorFieldPlots`"];
Get["VectorFieldPlots`VectorFieldPlots3D`"];

and the file structure is

Answer 3

My advice is to keep things like this as simple as possible. I have found that copying the official documentation is adequate and generates few (... no) error messages.

With v8, there appears to be a newer WRI style. Before this, usages were written

function::usage = "function[arguments, options] does ...";

An example of this form can be found in

ToFileName[{$AddOnsDirectory, AddOns, ExtraPackages, Utilities}, CleanSlate.m]

From v8 onwards, the style seems to have changed to

If[!ValueQ[function::usage],
 function::usage = "function[arguments, options] does ..."
];

An example of this form can be found in

ToFileName[{$AddOnsDirectory, AddOns, Packages, ANOVA}, ANOVA.m]

I have found no practical difference between the two versions, but your kilometerage may vary.