#summary Comment Tags

||Navigation>>||  [Manual Start]  || [CommentAttributes Next - Comment Tag Attributes] || [WritingDocumentation  Previous - Writing Doc Comments] ||

----------

= 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 [http://en.wikipedia.org/wiki/Namespace_%28computer_science%29 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 ([TagFunction @function], [TagConstructor @constructor], [TagEvent @event] and [TagIfunction @ifunction].

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

You can use [TagConstructor @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 [TagEvent @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 [TagIfunction @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 [TagVar @variable] and [TagProperty @property] are quite close to each other and have the same set of attributes.

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

The [TagProperty @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 [TagClass @class], [TagInterface @interface], [TagNamespace @namespace], [TagObject @object] and [TagStruct @struct] have similar structure, they serve different purposes.

All those tags are used to group together other tags, like [TagFunction @function], [TagVar @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 [TagInterface @interface] tag is used to describe something that may be implemented or mixed in.

The [TagNamespace @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 [http://en.wikipedia.org/wiki/Namespace_%28computer_science%29 Wikipedia article]

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

The [TagObject @object] tag is conceptually close to [TagNamespace @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 [TagModule @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 [TagFile @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 [TagProject @project] tag is used to provide general information of your project, like  description, short summary, version, etc

-------------

||Navigation>>||  [Manual Start]  || [CommentAttributes Next - Comment Tag Attributes] || [WritingDocumentation  Previous - Writing Doc Comments] ||