Best Practice to write ::usage for own package functions

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

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.

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.