Questions on documenting JavaScript: JS types

Question

Considering I am going to work with a larger team in the future, I'm trying to teach myself some basic annotation and documentation principles for front-end languages. Currently I'm working on JS.

For the most part, I'm using Google's Style Guide as a go-to, but I still have some questions.

Let's say I have an ajax function like so:

function initFunction(src, wrapper) {
  $.getJSON(src, {
    format: "json"
  }).done(function(data) {
    var wrapper = $(wrapper),
      contents = callAnotherFunction($(data)[0]);

    // Populates the wrapper element.
    wrapper.append(contents );

  }).fail(function(jqXHR, textStatus, errorThrown) {
    alert(textStatus + ": " + errorThrown);
  });
}

The function has two @param, src and wrapper. Here are some questions.

callAnotherFunction(), then, takes as an argument an Object and it should return some HTML.

1. what's the type of src? Considering it's JSON, {Object}?
2. what's the type of wrapper? Considering it's a value such as "#myId", String?
3. what's the return type of this function? It's a void function, but I don't know what I would call its return type. Does it return null?
4. what's the type of HTML that you can append to an element? Is it a String?
5. what is the JSDoc convention for displaying all of this? Something like this?

/** * This is a description of this function. It gets a JSON file, uses it as * a jQuery object, and then call another function with the new data. * @param {Object} src JSON file to parse. * @param {String} wrapper HTML element to use as a wrapper for the output. * @return {Null} */

Answer 1

1. The type of the argument is not related to what it represents, but is the JavaScript type of the argument. In your case src is a string containing the url (it doesn't matter retrieving the url retrieves JSON) so the type is string. More info here.
2. Yes, it's a string.
3. If the function doesn't have a return value just don't mention it in the JSDoc.
4. As per JQuery documentation it's:

Type: htmlString or Element or Array or jQuery

DOM element, array of elements, HTML string, or jQuery object to insert at the end of each element in the set of matched elements.

So it depends on what you want to document your function as accepting. If you want to document it as accepting multiple types, you use parentheses and the | character (example below).

5. Close, but you don't want a return type. Some people also put a blank line between the description and the params, but that's not required by the parser.

   /**
    * This is a description of this function. It gets a JSON file, uses it as 
    * a jQuery object, and then call another function with the new data.
    *
    * @param  {Object} src     JSON file to parse.
    * @param  {(String|jQuery|DOMElement)} wrapper HTML element to use as a wrapper for the output.
    */
   function initFunction(src, wrapper) {
   // ...
   

   In the above, we've indicated that wrapper can be a string, jQuery object, or DOMElement. We didn't get into the details of it possibly being an array, nor whether the string is a selector or an HTML fragment. The description would need to handle that. With a lot of choices, you may have to fall back on {*}.

   If the parser may not be able to tell if this is a function, you'd also add the @function tag:

   /**
    * This is a description of this function. It gets a JSON file, uses it as 
    * a jQuery object, and then call another function with the new data.
    *
    * @function
    *
    * @param  {Object} src     JSON file to parse.
    * @param  {(String|jQuery|DOMElement)} wrapper HTML element to use as a wrapper for the output.
    */
   var initFunction = function(src, wrapper) {
   // ...
   

   Depending on context, you may prefer @method to @function (they're synonyms).