Document my code: a few questions

[jjshell]

Hello,

I'm in the process of documenting my code. Here are a few questions I have. Tell me if I'm doing it right or wrong:

1.
A param can be either a string, an integer or a boolean:
@param{(String|Integer|Boolean)} myParam

2.
A method returns "this" (the "MyObject" itself)
@return {MyObject.Instance}

3.
A boolean param is optional
@param {Boolean} (optional)

4.
A param is either the window object, window.document or an HTMLDocument
@param {Object|HTMLElement} myParam

5.
A param is a function
@param {Function} myParam

6.
If a param is optional, how to specifiy its default value?
@param {Boolean} (optional) Default is true

7. If I make a reference to another method of an object, how to do it properly?
@see otherMethod
(should there be brackets? Should the method be prefixed by the Object name?)

8. If an integer is returned, should I rather say it's a number?
@return {Number}
vs.
@return {Integer}

All the best.

-jj.

[John_Betong]

I prefer to document functions, etc with a "blackbox" approach so there is no need to delve into the function to see what it is doing.

# MyModel Class function list
#   public function get_customer($iStart=0, iEnd=10, & aByRef=array())
#   public function set_customer($idCust=0, $aValues=array())


/* #########################################
#
#  usage:
#         $this->MyModel->get_customers()
#         $this->MyModel->get_customers(22,15)
#         $this->MyModel->get_customers(5,10, $aByRef)
#  
#  result:
#         number of customer found
#
#  returnByRef:
#         aByRef=array() # if and only if parameter passed
#          
########################################### */
public function get_customers($iStart=0, iEnd=10, & $aByRef=array())
{
  $result=0; # default

  # reams of optimised code goes here

  return $result;
} 

[Jeff Mott]

Tell me if I'm doing it right or wrong:

Whether you're going it right or wrong very much depends on what generator you're coding against. When we use these doc comments, we usually intend for some program to read those comments and automatically generate documentation for us. Today, I believe the most popular tool for PHP is phpDocumentor, and you can look up their documentation for the param tag.

EDIT: Oops, I'm not in the PHP forum, so phpDocumentor is probably not what you want. Though, the same principle holds, that whether you're doing it right or wrong depends on which generator you're coding for. Perhaps you're coding for the Closure Compiler?

[jjshell]

Thanks for your input.

Yep, coding for Closure. And back to my original question

[Jeff Mott]

#1 seems correct, though the parentheses are unnecessary. For #2, I don't see anything in the documentation. You'll probably have to use the param's description. For #3, the Closure-specific documentation says optional arguments are marked with an equal sign {Boolean=}. However, the generic JSDoc Toolkit documentation says optional arguments are are marked with square brackets @param {Type} [varname] Description. Which of those two styles you use depends on which one works when you try generating the documentation. For #4, "Object" is neither the window nor the document. For #5, the documentation says functions are annotated as {function(string, boolean)}. For #6, the Closure-specific documentation doesn't cover this case, but the generic JSDoc documentation says @param {Type} [varname="defaultValue"] Description. For #7, the Closure-specific documentation doesn't cover this case, but the generic JSDoc documentation says @see ClassName#methodName. For #8, JS doesn't have an integer type, so number is correct.

[jjshell]

Awesome!!!! +1

Thank you so much.

For #4, how would I describe a type of window and document? {Window}? and {Document} for document? and {HTMLElement} for, well, an HtmlElement?

[Jeff Mott]

For #4, how would I describe a type of window and document? {Window}? and {Document} for document? and {HTMLElement} for, well, an HtmlElement?

Yup.

[jjshell]

Yay

WHat type would be the event object? {Object}?

[Jeff Mott]

WHat type would be the event object? {Object}?

{Event}

[jjshell]

A big +1 ot you, Jeff.

[jjshell]

One more question: what if I pass the window object (or the event object) to a function, would it be better to write:

@param {function({Window})} / @param {function({Event})}

or

@param {function(window)} / @param {function(event)}

[Jeff Mott]

With the capital letters. Because you're not defining the concrete object that ultimately gets passed. Rather, you're defining the param's type. The type means the param may be any object that implements the Window interface or the Event interface.

[jjshell]

Capital letter and brackets?

[Jeff Mott]

Based on the example in the closure docs, it would seem to be without brackets.