When documenting objects that are not explicitly included in the code (e.g., objects passed via successCallbacks), avoid creating extra new classes.
Ideally, document the object inline as HTML list in the method or field that uses it. LABKEY.Security contains many examples.
If you do need to create an arbitrary class to describe an object, use the @name tag. See LABKEY.Domain.DomainDesign for a simple example. You'll probably need to create a new class to describe the object IF:
Many classes use the object, so it's confusing to doc the object inline in only one class.
The object is used as the type of many other variables.
The object has (or will have) both methods and fields, so it would be hard to distinguish them in a simple HTML list.
Caution: Watch for a bug if you use metatags to write annotations once and use them across a group of enclosed APIs. If you doc multiple, similar objects that have field names in common, you may have to fully specify the name of the field-in-common. If this bug is problematic, fields that have the same names across APIs will not show links.
An example of a fix: Query.js uses fully specified @names for several fields (e.g., LABKEY.Query.ModifyRowsOptions#rows).
When adding a method, event or field, please remember to check whether it is correctly marked static.
There are two ways to get a method to be marked static, depending on how the annotations are written:
Leave both "prototype" and "#" off of the end of the @scope statement (now called @lends) for a @namespace
Leave both "prototype" and "#" off of the end of the @method statement
Note: If you have a mix of static and nonstatic fields/methods, you may need to use "prototype" or "#" on the end of a @fieldOf or @memeberOf statement to identify nonstatic fields/methods.
As of 9.3, statics should all be marked correctly.
Check out the formatting of @examples you’ve added – it’s easy for examples to overflow the width of their boxes, so you may need to break up lines.
Remember to take advantage of LabKey-defined objects when defining types instead of just describing the type as an {Object}. This provides cross-linking. For example, see how the type is defined for LABKEY.Specimen.Vial#currentLocation.
Use @link often to cross-reference classes. For details on how to correctly reference instance vs. static objects, see NamePaths.
Cross-link to the main doc tree on labkey.org whenever possible.
Deprecate classes using a red font. See GridView for an example. Note that a bug in the toolkit means that you may need to hard-code the font color for the class that’s listed next in the class index (see Message for an example).
