General Information

These provide descriptions for the function or object:

• summary: A short statement of the purpose of the function or object
• description: An extended description of the function or object
• returns: A description of what the function returns (does not include a type)
  

General Function Information

function(){
  // summary: Soon we will have enough treasure to rule all of New Jersey.
  // description: Or we could just get a new roomate.
  //    Look, you go find him.  He don't yell at you.
  //    All I ever try to do is make him smile and sing around
  //    him and dance around him and he just lays into me.
  //    He told me to get in the freezer 'cause there was a carnival in there.
  // returns:  Look, a Bananarama tape!
}

Object Function Information

Has no description of what it returns

{
  // summary: Dingle, engage the rainbow machine!
  // description: Tell you what, I wish I was--oh my g--that beam,
  //    coming up like that, the speed, you might wanna adjust that.
  //    It really did a number on my back, there. I mean, and I don't
  //    wanna say whiplash, just yet, cause that's a little too far,
  //    but, you're insured, right?
}

Function Assembler Information (defineWidget/declare)

We can sometimes end up in situations where a function declaration is invisible, being created by the call. In this case, there's no way to associate our comments directly with the function. If you encouter this situation, the data can be associated through the passed object.

Note, this only works if there is no initializer function parameter. If there is, this will be ignored.

dojo.declare(
  "foo",
  null,
  {
    // summary: Phew, this sure is relaxing, Frylock.
    // description: Thousands of years ago, before the dawn of
    //    man as we knew him, there was Sir Santa of Claus: an
    //    ape-like creature making crude and pointless toys out
    //    of dino-bones, hurling them at chimp-like creatures with
    //    crinkled hands regardless of how they behaved the
    //    previous year.
    // returns: Unless Carl pays tribute to the Elfin Elders in space.
  }
);

Parameters

Simple Types

If you're only going to be describing the type of the object, you should do it in the main parameter definition block.

function(/*String*/ foo, /*int*/ bar)...

Type Modifiers

There are some modifiers you can add after the type

• ? means optional
• ... means the last parameter repeats indefinitely
• [] means an array
  

function(/*String?*/ foo, /*int...*/ bar, /*String[]*/ baz)...

Full Parameter Descriptions

If you want to also add a description, you should move to the initial comment block.

The format for the general information is: key Descriptive sentence
The format for paramters and variables is: key type Descriptive sentence

Where key and type can be surrounded by any non-alphanumeric characters.

function(foo, bar){
  // foo: String
  //    used for being the first parameter
  // bar: int
  //    used for being the second parameter
}

Variables

Instance variables, prototype variables and external variables can all be defined in the same way. There are many ways that a variable might get assigned to this function, and locating them all inside of the actual function they reference is the best way to not lose track of them, or accidentally comment them multiple times.

function foo(){
  // myString: String
  // times: int
  //    How many times to print myString
  // separator: String
  //    What to print out in between myString
  this.myString = "placeholder text";
  this.times = 5;
}
foo.prototype.setString = function(myString){
  this.myString = myString;
}
foo.prototype.toString = function(){
  for(int i = 0; i < this.times; i++){
    dojo.debug(this.myString);
    dojo.debug(foo.separator);
  }
}
foo.separator = "=====";

Variable Comments in an Object

The parser takes the comments in between object values and applies the same rules as if they were in the initial comment block:

{
  // key: String
  //    A simple value
  key: "value",
  // key2: String
  //    Another simple value
}

Return Value

Because a function can return multiple types, the types should be declared on the same line as the return statement, and the comment must be the last thing on the line. If all the return types are the same, the parser uses that return type. If they're different, the function is considered to return "mixed".

function(){
  if(arguments.length){
    return "You passed argument(s)"; // String
  }else{
    return false; // Boolean
  }
}

Still Up for Discussion

Pseudo-Code (implemented)

There are some instances where you might want an object or function to appear in documentation, but not in Dojo, nor in your build. To do this, start a comment block with /*=====. The number of = can be 5 or more. At the moment, this is only useful for declaring an object type that doesn't appear in code.

The parser simply replaces the /*===== and =====*/ with whitespace at the very start, so think of these blocks as if they were commented out.

/*=====
module.pseudo.kwArgs = {
  // url: String
  //    The location of the file
  url: "",
  // mimeType: String
  //    text/html, text/xml, etc
  mimeType: ""
}
=====*/

function(/*module.pseudo.kwArgs*/ kwArgs){
  dojo.debug(kwArgs.url);
  dojo.debug(kwArgs.mimeType);
}

Multiple Parameter/Variable Types

Most of this can (and probably should) be handled with the argument signature solution below, but there still might be a better way to figure this thing out. In some cases, you can have, say, an array or a value for the same parameter. In some cases, you can pass a string, or an object type. It seems to be a pretty common thing to say "this will be called using toString()". Is there a good way to support that? The type||type solution gets problematic when the code is complicated, so it seems like a quick fix that isn't a true solution.

Argument Signature (unimplemented)

Since Javascript has no typing, or argument contstraints, a lot can happen at run time. To handle this, we're allowing the changing (or removal) of parameter types at the beginning of any logical block (if/else/switch). You are also allowed to change the summary value.

The only thing required is that the key, branch, is added to indicate that this is a branch that is changing the argument signature.

If this logical block contains a return statement, it will be factored for only this block. This means that the overall return type for the function ignores these return types when calculating what it returns. This block uses not only the function return, but the newly introduced returns. Note: This means that the returns key can also be redeclared here.

Each paramName must match the parameter name it corresponds to, and each value must have the expected object type (see "Parameter Types" above).

Example:

/*=====
module.hello.posessionsObject = {
  // summary: Possible posessions you might have
  // car: String       The type of car you have
  // lollipop: String  The flavor of your lollipop
  car: "",
  lollipop: ""
}
=====*/

module.hello = function(/*String*/ timeOfDay,
                        /*String*/ emotion,
                        /*module.hello.posessionsObject*/ posessions){
  // summary: Prints a custom greeting
  // returns: A sentence using all provided parameters.
  var message = "Good ";
  if(typeof timeOfDay == "string"){
    message += timeOfDay + ". ";
  }elseif(timeOfDay instanceof Date){
    // branch
    // timeOfDay: Date
    if (timeOfDay.getHours() < 12) {
      message += "morning. ";
    }else if (timeOfDay.getHours() < 15) {
      message += "afternoon. ";
    }else{
      message += "evening. ";
    }
  }else{
    message = "";
  }

  if(typeof emotion == "string"){
    message += "I see you're feeling " + emotion + ". ";
  }else{
    // branch
    // emotion: Number A rating from 0 (bad) to 10 (great)
    emotion = parseInt(emotion);
    if (emotion < 4){
      message += "I'm sorry you're not feelign well. ";
    }else if(emotion < 7){
      message += "I see you're feeling well.";
    }else{
      message += "Looks like you're feeling great. ";
    }
  }

  for(var posession in posessions){
    message += " You have a " + posession
            + " that is a " + posessions[posession] + ". ";
  }

  return message; // String
}

This will emulate the following calls:

• String module.hello(String timeOfDay, String emotion, module.hello.posessionObject posessions);
• String module.hello(Date timeOfDay, String emotion, module.hello.posessionObject posessions);
• String module.hello(String timeOfDay, Number emotion, module.hello.posessionObject posessions);
• String module.hello(Date timeOfDay, Number emotion, module.hello.posessionObject posessions);

Displaying varying argument signatures

On the main page, we will show the various signatures with their summaries.

On the source code display page, the various blocks of code will have different backgrounds corresponding to a function signature. By default, all branches will be shown, but a user will be able to change the signature and see how it affects the source code.

Using the Doctool locally

If you are a developer who has marked their code up using this syntax and want to test to make sure it is correct, you can run the doctool yourself locally. See DocParserInstructions for details on how to do so.