Comment Tags

jGrouseDoc allows documentation of the following artifacts:

• Functions, constructors, event handlers and function interfaces (AKA callback signatures)
• Variables and properties
• Classes, interfaces, namespaces, objects and structures (also known as Logical Containers since they contain other comment tags and are essentially forming namespaces in your code)
• Files and modules (also known as Physical Containers)
• Project attributes

Functions, Constructors, Event Handlers and Function Interfaces

The documentation for functions, constructors, event handlers and function interfaces are very similar and differs only with the name of the tag being used (@function, @constructor, @event and @ifunction.

Obviously, the @function tag could be used to document both standalone functions and functions that are members of classes, interfaces, etc.

You can use @constructor tag to document functions that are either true constructors (i.e. the ones invoked in conjunction with new operator) and initializers, if you are using frameworks that rely on generic constructors that in turn call initializers (like Dojo).

The @event tag could be used to document placeholders for member methods that would be triggered whenever certain event occurs. Typical application of this tag would be to document cases like "in case of such event, check if the instance of the event target has a method with appropriate name and invoke that method with these arguments". Of course, this is not the only possible application of @event tag. You can also use it to document event producers, like custom events in YUI.

The @ifunction tag is particularly useful when you need to document the signature of a callaback function that is passed as a parameter or a function that is returned as a result by another function, etc.

Variables and properties

The tags @variable and @property are quite close to each other and have the same set of attributes.

The difference is in semantics. Normally you would use @variable to describe either a standalone variable or a member variable that indeed physically exist in your code.

The @property tag could be used, for example, to describe cases when setting or reading of certain value triggers some kind of processing.

Classes, interfaces, namespaces, objects and structures

Although tags @class, @interface, @namespace, @object and @struct have similar structure, they serve different purposes.

All those tags are used to group together other tags, like @function, @variable, etc.

You would typically use @class to document something that may be instantiated. Note that from jGrouseDoc perspective it is absolutely irrelevant how support for classes is implemented in the library of your choice, be it Dojo, Prototype, Base, jQuery, jGrouse, you name it.

The @interface tag is used to describe something that may be implemented or mixed in.

The @namespace tag is used to describe n abstract container or environment created to hold a logical grouping of unique identifiers (i.e., names). An identifier defined in a namespace is associated with that namespace. The same identifier can be independently defined in multiple namespaces. That is, the meaning associated with an identifier defined in one namespace may or may not have the same meaning as the same identifier defined in another namespace. (This definition was copied from corresponding Wikipedia article

You can use the @struct tag to describe a data-only structure, if that fits your style.

The @object tag is conceptually close to @namespace. You can use it, for example, to describe a vanilla JavaScript object.

Files and modules

While classes, namespaces, etc are used to describe the logical structure of your application or library, files and modules are used to describe the physical structure.

The @module tag could be used to describe a piece of code that could be loaded dynamically and/or has dependencies on other modules that should be loaded and initialized upfront. Dojo and jGrouse modules would be the best examples of that concept.

The @file tag is used to provide information about a source file.

Usually a module is described in one and only one source file.

Project attributes

The @project tag is used to provide general information of your project, like description, short summary, version, etc