Coffeed makes no assumptions about the code, and in-fact doesn't even read it.
All documented symbols belong to one of the following:
- @namespace
- @module
- @class
- @mixin
If none of the above are present, then the file is treated as the top-level element and the document symbols are attached to that.
In general, any tag can have modifiers associated with it. Modifiers are other tags which add data to the tag being modified, and must appear within the same documentation block as the tag being modified. An example is the @struct tag, which can be modified with the @field tag.
@struct myStruct
@field {number} num=0 Number of widgets.
@field {string} fav='' Name of favorite widget.
@field {Array<Widget>} widgets=[] Array of widgets.
The above documentation block defines a struct named myStruct with three
fields. The @field are the modifier tags, acting on the modified tag @struct.
Block tags define possibly large bodies of code with follow on methods, properties, members, etc. documented in the follow-on lines of code. Thus, once a block-tag is encountered it is assumed that follow-on documentation symbols are members of the previous block.
Used to define a CoffeeScript class, a symbol that is intended to be
called with the new keyword.
This class should not be instantiated directly, but instead on of it's ancestors. should be used.
Documents that this class extends from the parent class.
Document a namespace object such as window or global. A namespace is
essentially just an Object.
Document a CommonJS or AMD module.
This object mixes in all the members from another object.
Classes, modules, namespaces or files can all have members attached to them. These member may be any of the following tags.
Describe a function or method.
Document the parameter to a function.
Document the default value of a parameter.
What does the 'this' keyword refer to here?
Document the return value of a function or method.
Describe what errors could be thrown.
Same features as @function, but documents the special method within a CoffeeScript that acts as the class's constructor. See @function.
Document a property of an object.
Documents a setter function (see @function) for this property.
Documents a getter function (see @function) for this property.
This symbol is meant to be read-only.
Document a custom type.
Document a member.
Document the default value of a member.
Document a collection of related properties.
Defines a struct, a standardized object representation.
Defines a field on a struct. Fields will always be added to the most recently documented struct.
Document an object as a constant.
Members can be modified in a variety of ways.
This tag can be used to override the assumed parent-child relationship between a member and it's parent.
Also, classes, namespaces, and modules can use @memberof to establish hierarchical relatinoships. i.e.
@class MyClass @memberof myModule/subModule
would establish the class at the namepath myModule/subModule.MyClass
Note too, that the last module in a namepath is essentially identical to a namespace.
Indicate that a symbol overrides its parent.
This member must be defined by an inheriting class.
This member is static, so it belongs to the prototype of a class.
Documents an instance member, `MyClass#instanceMember'. By default, members are instance members on classes and static on namespaces and modules (since namespaces and modules should not be instantiated). To uglify documentation however, this can be overridden.
Both members and classes may have access modified tags.
Specify the access level of this member (private, public, or protected).
This symbol is meant to be private.
This symbol is meant to be protected.
This symbol is meant to be public.
Members, classes, modules or namespaces may define, fire, or emit events.
Events should be namespaces with colons, i.e.
myModule/submodule.MyClass:myEvent:subEvent myNamespace.subNamespace.MyClass:eventName
etc...
Documents an event.
Describe the events this method may fire.
Describe a file.
This file requires the documented module.
Defines the author of the file.
Defines the version of the file.
Document some copyright information about the file.
Identify the license that applies to the code in this file.
Document that a member, class, symbol, or other item is deprecated and is no longer preferred.
Provide an example of how to use a documented item.
Insert a link to an included tutorial file.
Refer to some other documentation for more information.
When was this feature added?
Document tasks to be completed.
Ignores the entire document block.
By default, the first sentence of a documentation block is the summary, and the the entire text is the description. This may be overridden with the @description and @summary tags.
A shorter version of the full description. See @description.
Document an inner object. This essentially prevents breaking out of the current documentation block and starting a new one.
Document the name of an object.
Document the type of an object.
Document a global object.
Indicate that a symbol should inherit its parent's documentation.