JavaScript Documentation Questions: JS Types

Question

Given that in the future I will work with a larger team, I try to teach myself the basic principles of annotation and documentation for front-end languages. I am currently working on JS.

For the most part I use the Google Style Guide , but I still have some questions.

Say I have an ajax function like this:

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 a few questions.

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

• what type of src? Given this JSON, {Object} ?
• what type of wrapper? Given this value, such as "#myId" , String?
• what type of return function? This is a void function, but I don’t know what I would call it a return type. Does it return null?
• What type of HTML can be added to an element? Is this a String ?
• What is the JSDoc convention to display all of this? Something like that?

/** * 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

• The type of the argument is not related to what it represents, but is a type of JavaScript argument. In your case, src is a string containing the url (it doesn't matter if it retrieves the URL to receive JSON), so the type is a string. More details here .
• Yes, this is a string.
• If a function does not have a return value, just do not mention it in JSDoc.
• According to jQuery Documentation :

Type: htmlString or element or array or jQuery

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

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

5. Close, but you do not need a return type. Some people also put an empty line between the description and parameters, but this is 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 example, we indicated that wrapper can be a string, jQuery or DOMElement object. We did not get any details that this could be an array, and whether the string is a selector or HTML fragment. A description would have to handle this. If you have a large number of options, you may need to return to {*} .

   If the analyzer cannot determine if this is a function, you will 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 the context, you may prefer from @method to @function (these are synonyms).

Answer 2

As Emanuele already said, the first argument can only be a string representing the URL.

However, the second parameter (wrapper) can be either a string or a DOM element . Not just a string.

I do not know how you could instruct JSDoc that a variable can be of two different types.

Answer 3

You must use the jQuery JSDoc extern file first.
Annotate functions accordingly; functions are annotated in this way because of an external jQuery file.

 /** * @param {!string} src * @param {(jQuerySelector|Element|Object|Array<Element>|jQuery|string|function())=} wrapper */ 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); }); } /** * @param {!Object} obj * @return {(string|Element|Array<Element>|jQuery|function(number,string))} */ function callAnotherFunction(obj) { . . . } 

Answer 4

The minimal functionality documentation that I usually do is:

 /** Purpose: state the purpose of the function parameters: src: string, required: the url to the api service. [paramName: type, option: purpose. {list individual parameters} Assumption: describe any dependencies. Any callback, etc. Return: string, json format. */ function foo(src, param) {} 

Put yourself in shoes. What you need to know quickly before trying to make any changes to your user code.